Query Counter MCP Server

Query Counter MCP Server

An MCP (Model Context Protocol) server that logs all your LLM queries to a local file and provides interactive analytics. Track your interactions with Claude, ChatGPT, Gemini, and other models with detailed categorization and visualizations.

Features

• Dual Format Logging: CSV (default) or Markdown format
• Interactive Dashboard: Beautiful HTML analytics dashboard with charts and KPIs
• Category Tracking: Organize queries by type (coding, research, debugging, etc.)
• Rich Analytics: Track query volume, model usage, category distribution, and trends
• Configurable: Custom log file location and format
• MCP Compatible: Works with Claude Desktop and other MCP clients

Installation

1. Clone the repository:

git clone https://github.com/bjulius/QueryCounterMCP.git
cd QueryCounterMCP

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "query-counter": {
      "command": "node",
      "args": [
        "/path/to/your/QueryCounterMCP/build/index.js"
      ]
    }
  }
}

Replace /path/to/your/QueryCounterMCP/ with the actual path where you cloned the repository.

Example paths:

• macOS: "/Users/yourname/projects/QueryCounterMCP/build/index.js"
• Windows: "C:\\Users\\YourName\\Projects\\QueryCounterMCP\\build\\index.js"

Environment Variables

Customize the logging behavior:

{
  "mcpServers": {
    "query-counter": {
      "command": "node",
      "args": [
        "/path/to/your/QueryCounterMCP/build/index.js"
      ],
      "env": {
        "QUERY_LOG_FORMAT": "csv",
        "QUERY_LOG_PATH": "/path/to/your/custom/log.csv"
      }
    }
  }
}

Available Options:

• QUERY_LOG_FORMAT: "csv" (default) or "md" for Markdown
• QUERY_LOG_PATH: Custom path for the log file

Usage

Logging Queries

The MCP server automatically logs queries made through Claude Desktop. The AI (Claude) determines the appropriate category based on the conversation context.

Example interaction:

User: Help me debug a React component that's not rendering properly
Claude: [Uses the log_query tool automatically]
        - model: "Claude Sonnet 4.5"
        - query_summary: "Help me debug a React component"
        - category: "debugging" [AI selected]

Tool Parameters:

• model (required): The LLM model name (selected by AI)
• query_summary (required): Brief description of the query (generated by AI)
• category (optional): Query category (automatically selected by AI based on query type)

Viewing the Dashboard

Use the show_dashboard tool to generate and view analytics:

Please show me the dashboard

This will:

1. Generate an interactive HTML dashboard from your query data
2. Automatically open it in your default browser
3. Display real-time analytics and visualizations

Dashboard Features

The interactive dashboard includes:

KPI Cards

• Total Queries Today: Number of queries logged today (highlighted)
• Average Queries Per Day: Mean queries across all days
• Total Number of Categories: Unique categories used
• Max Queries in a Day: Your highest query volume day

Visualizations

• Categories by Percent: Horizontal bar chart showing category distribution
• Models by Percent: Horizontal bar chart of AI model usage
• Total Queries by Day: Daily query volume over time

Design

• Clean, modern interface with responsive layout
• Interactive charts powered by Chart.js
• Data labels on all visualizations for easy reading
• Personalized with your name in the subtitle

Query Categories

The AI automatically selects the most appropriate category for each query. These categories help organize and analyze your query patterns:

Development & Code

• coding - Writing, debugging, or explaining code
• refactoring - Code improvements, restructuring, optimization
• testing - Writing or running tests, test analysis
• debugging - Troubleshooting errors, investigating issues

Analysis & Research

• data-analysis - Analyzing data, visualizations, statistics
• research - Information lookup, documentation searches, learning

Project Management

• documentation - Writing/updating docs, README files, comments
• configuration - Settings, setup, tool configuration, environment

Interaction

• clarification - Follow-up questions, asking for details
• selection - Short confirmations, choosing options
• navigation - UI commands, viewing files, moving around
• conversation - General chat, greetings, feedback

Log File Format

By default, queries are logged to QueryTrackMCP.csv in CSV format:

timestamp,date,model,catego