Claude Stats

Claude Stats MCP provides AI usage statistics and analytics for Claude Code through two MCP implementations: a Node.js version and a Python version. It lets you run local analysis in STDIO mode or expose a remote HTTP endpoint for integration, enabling quick insights into your Claude usage patterns and trends.

How to use

To use this MCP server with your MCP client, choose the integration method that fits your workflow. For local development, run the Node.js version in STDIO mode and connect through Cursor. For remote access or centralized deployments, run the Python version in HTTP mode to expose an endpoint at http://localhost:8000/mcp. Once started, you can issue tool-based questions like who used the most today, what usage looks like this month, or compare two users.

Typical usage patterns include: 1) Start the server in your preferred mode. 2) From your MCP client, query daily or monthly usage, top users, or generate reports. 3) If using HTTP, point your client to the /mcp endpoint. 4) Use the provided tools to analyze trends, detect anomalies, and produce concise summaries.

How to install

Prerequisites depend on the chosen implementation.

Node.js version (STDIO mode) install and start steps:

./start-node.sh

The script automatically checks Node.js, installs dependencies, and runs in STDIO mode suitable for Cursor configuration.

Python version (HTTP and STDIO modes) install steps:

./start-python.sh

The script automatically checks the Python environment, creates a virtual environment, installs dependencies, and supports both STDIO and HTTP modes. For HTTPS remote use, you can access the endpoint at http://localhost:8000/mcp after startup.

Manual startup without scripts (example commands shown in the source):

# Node.js manual start
cd node-mcp-demo
npm install
export KEYS_CONFIG_PATH=/path/to/keys.json
npm run dev

# Python manual start
cd python-mcp-demo
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# STDIO 模式
KEYS_CONFIG_PATH=/path/to/keys.json python server.py

# HTTP 模式
KEYS_CONFIG_PATH=/path/to/keys.json \
MCP_TRANSPORT=http \
MCP_PORT=8000 \
python server.py

Additional setup notes

Cursor configuration examples are provided to connect either the Node.js STDIO server or the Python HTTP/STDIO server. Ensure the KEYS_CONFIG_PATH points to a valid keys.json file with your API credentials.

# Node.js Cursor config (STDIO)
{
  "mcpServers": {
    "claude_stats_node": {
      "command": "npx",
      "args": ["tsx", "/path/to/node-mcp-demo/src/index.ts"],
      "env": {
        "KEYS_CONFIG_PATH": "/path/to/keys.json"
      }
    }
  }
}

Security and best practices

Protect your keys.json and API credentials. Use least-privilege access and rotate keys as needed. When exposing an HTTP endpoint, consider network access controls to restrict requests to trusted clients.

Troubleshooting

If you encounter issues, verify the following: Node.js version compatibility for the Node.js variant, Python version compatibility for the Python variant, and that KEYS_CONFIG_PATH points to a valid keys.json file. For Node.js issues, re-install dependencies and re-run the dev script. For Python issues, recreate the virtual environment and install requirements.txt again.

Notes

Eight MCP tools are available for querying statistics and generating reports. You can interactively request insights via the MCP client and rely on the built-in analysis capabilities.

Available tools

query_today_stats

Query statistics for today, such as total cost or usage metrics for the current day.

query_monthly_stats

Query statistics for the current month to analyze monthly usage.

query_user_stats

Query usage statistics for a specific user by name or identifier.

query_top_users

Get a ranking of top users by usage or engagement.

compare_users

Compare usage metrics between two or more users.

analyze_usage_trend

Analyze usage trends over time to identify patterns.

detect_anomalies

Detect anomalies or threshold breaches in usage.

generate_report

Generate a concise report of statistics for a given period.