MCP Integration

The claude-telemetry MCP server lets you ask Claude about your usage in natural language. Instead of opening the dashboard, just ask:

"How much did I spend this week across all machines?"

What Is MCP?

Model Context Protocol (MCP) is a standard for connecting AI assistants to external tools. claude-telemetry provides an MCP server with 12 tools that Claude can call to answer questions about your usage.

Setup

cc-telemetry setup-mcp

This registers the MCP server in ~/.claude.json. You can also set it up as part of the unified setup wizard (cc-telemetry setup).

Restart Required

After configuring, restart Claude Code for the MCP server to become available.

Available Tools

Data Tools (7)

Tool	Description
get_daily_usage	Daily token and cost breakdown
get_weekly_usage	Weekly aggregated usage
get_active_blocks	Current 5-hour block status
get_rate_limits	5-hour and weekly rate limit usage
get_machines	List of connected machines with status
get_projects	Usage by project directory
get_plan_savings	Plan vs API cost comparison

Analytics Tools (5)

Tool	Description
compare_periods	Compare two time periods (e.g., this week vs last week) with cost diff, token diff, and top movers
get_trends	Linear regression with direction detection (UP/DOWN/STABLE) and 7-day projection
detect_anomalies	Z-score based anomaly detection with configurable threshold
compare_projects	Side-by-side project comparison
get_cost_forecast	Moving average forecast with confidence range (low/high)

Example Queries

Once configured, you can ask Claude questions like:

• "How much did I spend this week vs last week across all machines?" — triggers compare_periods
• "What's my most expensive project?" — triggers get_projects
• "Any anomalies in my usage this month?" — triggers detect_anomalies
• "What's my forecast for the next 7 days?" — triggers get_cost_forecast
• "Am I close to my rate limit?" — triggers get_rate_limits
• "Compare project-alpha and project-beta" — triggers compare_projects
• "What's the trend in my daily spending?" — triggers get_trends

Technical Details

• Built with FastMCP using stdio transport
• Works in both Claude Code CLI and VS Code extension
• Each tool returns structured JSON that Claude interprets and summarizes
• The server connects to your Supabase database using the same credentials as the agent

Troubleshooting

MCP tools not appearing

1. Run cc-telemetry doctor — check that "MCP server registered" shows ✓
2. Restart Claude Code completely (not just reload)
3. Verify ~/.claude.json contains the cc-telemetry MCP entry

Tools return errors

• Check that your Supabase credentials are valid: cc-telemetry sync --verbose
• Ensure the agent has synced at least once: cc-telemetry status