Query Counter MCP

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

1. Install dependencies:

npm install

1. 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,category,query_summary
2025-10-15T18:20:37.516Z,10/15/2025 2:20:37 PM,Claude Sonnet 4.5,debugging,Help me debug a React component
2025-10-15T18:22:15.342Z,10/15/2025 2:22:15 PM,Claude Sonnet 4.5,coding,Create a user authentication function
2025-10-15T18:25:43.891Z,10/15/2025 2:25:43 PM,Claude Sonnet 4.5,data-analysis,Analyze sales data trends

CSV Format Benefits:

• ✅ Easy to import into Excel, Google Sheets, or Pandas
• ✅ Efficient for data analysis and reporting
• ✅ Compact file size
• ✅ Perfect for generating the interactive dashboard
• ✅ Can be opened and edited in any spreadsheet application

Alternative: Markdown Format

To use Markdown format instead, set QUERY_LOG_FORMAT=md in your environment variables. This creates a QueryTrackMCP.md file:

# LLM Query Log

This file tracks all queries made to various LLM models.

---

## 10/15/2025, 2:20:37 PM

- **Model**: Claude Sonnet 4.5
- **Category**: debugging
- **Query**: Help me debug a React component
- **Timestamp**: 2025-10-15T18:20:37.516Z

---

Markdown Format Benefits:

• ✅ Human-readable format
• ✅ Easy to browse in text editors
• ✅ Great for documentation and version control

Available Tools

log_query

Logs an LLM query to the tracking file.

Parameters:

• model (string, required): LLM model name
• query_summary (string, required): Brief query description
• category (string, optional): Query category

show_dashboard

Generates and displays an interactive HTML analytics dashboard.

Parameters: None

Output: Opens query-dashboard.html in your default browser with:

• 4 KPI cards with key metrics
• 3 interactive charts (categories, models, daily trends)
• Real-time data from your CSV log file

Development

# Install dependencies
npm install

# Build the project
npm run build

# Watch for changes during development
npm run watch

# Build and run
npm run dev

File Structure

QueryCounterMCP/
├── src/
│   └── index.ts          # Main MCP server code
├── build/
│   └── index.js          # Compiled JavaScript
├── QueryTrackMCP.csv     # Query log (CSV format)
├── query-dashboard.html  # Generated analytics dashboard
├── CLAUDE.md            # Instructions for Claude Code
└── README.md            # This file

Tips

1. Use categories consistently for better analytics
2. Run the dashboard regularly to track your query patterns
3. Set up automatic logging by integrating with your workflow
4. Export CSV data for custom analysis in Excel or Python
5. Customize the format based on your needs (CSV for analysis, MD for documentation)

License

MIT