@modelstat/mcp

Ask any MCP-compatible AI tool — Claude Desktop, Claude Code, Cursor, Cline, Continue, Zed — about your token spend directly in the chat.

• "How much did I spend on Cursor this week?"
• "Which project is driving my Claude Code cost?"
• "Show me recent sessions over $5."
• "Is my modelstat agent healthy?"

Uses the bearer token modelstat connect already wrote to ~/.config/modelstat/state.json — no separate auth.

Install

# Works inline — no global install needed.
npx -y @modelstat/mcp --help

# Or pin globally:
npm install -g @modelstat/mcp
modelstat-mcp

Wire it up

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows, unsupported at the moment):

{
  "mcpServers": {
    "modelstat": {
      "command": "npx",
      "args": ["-y", "@modelstat/mcp"]
    }
  }
}

Restart Claude Desktop. You'll see a 🔌 for the modelstat tools.

Claude Code

claude mcp add modelstat -- npx -y @modelstat/mcp

Cursor

Settings → Cursor Settings → MCP → Add new MCP server:

• Name: modelstat
• Command: npx
• Args: -y @modelstat/mcp

Cline / Roo

Settings → MCP Servers → Edit JSON:

{
  "mcpServers": {
    "modelstat": { "command": "npx", "args": ["-y", "@modelstat/mcp"] }
  }
}

Continue.dev

In ~/.continue/config.yaml:

mcpServers:
  - name: modelstat
    command: npx
    args: ["-y", "@modelstat/mcp"]

Tools

All tools are read-only. The MCP server never issues mutating calls.

| Tool | Purpose | |---|---| | get_spend_summary | Total $ and tokens for a range, split by tool + model. | | get_spend_by_project | Spend grouped by repo / project. | | get_spend_by_tool | Spend grouped by AI tool. | | list_recent_sessions | Most recent sessions with cost. | | get_device_status | Pairing + last-heartbeat status for this machine. |

range accepts: today, 7d, 30d, 90d, mtd, ytd.

Your MCP client may see additional tools beyond the ones listed above — the live catalog comes from the modelstat backend, and we add new query tools server-side. Ask your client to list available tools to see what's actually exposed for your account.

Auth & privacy

The MCP server reads the bearer token that modelstat connect stored locally. It never transmits that token anywhere except directly to the modelstat API (default https://modelstat.ai). Prompts, responses, and file contents never touch this process.

Override the API endpoint with MODELSTAT_API_URL (for self-hosted / dev). Override the state dir with MODELSTAT_STATE_DIR.

Troubleshooting

• modelstat is not paired on this machine — run curl -fsSL https://install.modelstat.ai | sh first.
• 401 responses — the bearer expired. Re-run modelstat connect.
• No data yet — the agent uploads within a few seconds of your first AI-tool session. Check modelstat status.

License

MIT.