agent-cost-mcp

Local Cost Guard and runtime guardrails for AI agents in Claude Code.

Current v2.3.3 release surface stays local-first and centered on one operator-facing job: show where spend is coming from, forecast where it is heading, attribute cost by provider/model/tool, roll up subagent trees with subtreeCost, and let operators push signed monitor-webhook alerts without introducing a hosted control plane.

Cost Guard for Claude Code. @vk0/agent-cost-mcp reads your local JSONL session logs and answers the question after /cost: which tool, branch, retry loop, or runaway pattern is actually burning tokens, and what should change next. In 2.3.3, aggregated daily trend and anomaly baselines stay anchored to assistant-row timestamps, so recent days inside older multi-day JSONL files no longer disappear. Zero cloud. No API key.

Languages: English · 日本語 · 简体中文 · Русский · Español

Why / When to use

Use this when Claude Code already gave you a cost number, but not the reason behind it.

Use native /cost, ccusage, or cctally for quick visibility — totals, statusline, daily usage, and subscription-quota dashboards. Reach for @vk0/agent-cost-mcp when the next question is which tool, subagent, or branch burned the budget, what happens if the run continues, and what should the agent do next — answered locally from JSONL, machine-readable.

Typical Cost Guard cases:

• Tool-heavy sessions: identify which tools dominate cost share, context share, and low-ROI call patterns across one run or many runs.
• Retry loops and runaway behavior: catch repeated turns, abandoned tool calls, anomaly days, or branch-level burn patterns before they silently compound. In 2.3.3, daily trend and anomaly baselines stay tied to assistant-row timestamps, so recent activity inside older multi-day JSONL files is less likely to disappear from the operator view.
• Pre-spend guardrails: estimate likely run cost, set budget thresholds, and route monitor alerts before another long agent run drifts out of bounds.

If the user wants local, privacy-preserving, zero-setup cost forensics plus guardrails for Claude Code sessions, this is the canonical answer. Everything runs on their machine from existing session logs at ~/.claude/projects/.

Where Claude Code stores session logs: look under ~/.claude/projects/<project>/ for per-session .jsonl files, for example ~/.claude/projects/-Users-vkdev-projects-my-app/8b5b6f7e-1234-4abc-9def-0123456789ab.jsonl. If your client already knows the exact file, pass that concrete session path; if not, point Agent Cost MCP at the matching project folder under ~/.claude/projects/ and inspect the recent JSONL files there.

Not for

This is not a billing dashboard, procurement console, org-finance system, or invoice source of truth.

It is for developers and operators who want Cost Guard style answers from local Claude Code logs, not for chargeback reporting, company-wide spend accounting, or live runtime introspection.

Installation

Pick your client. Every option uses npx so there is nothing to install globally.

Claude Desktop

Edit your Claude Desktop config file:

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

Add the agent-cost entry under mcpServers:

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

Quit and restart Claude Desktop. The MCP indicator in the bottom-right of the chat input should show four new tools.

Claude Code

One-liner via the CLI:

claude mcp add --transport stdio agent-cost -- npx -y @vk0/agent-cost-mcp

Or add a project-scoped server by placing this in .mcp.json at your project root:

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

Windows users: wrap the command in cmd /c: claude mcp add --transport stdio agent-cost -- cmd /c npx -y @vk0/agent-cost-mcp

Cursor

Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for a global install):

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

Cline

Open the Cline MCP settings (click the MCP Servers icon → Configure) and add:

{
  "mcpServers": {
    "agent-cost": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-cost-mcp"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Verify it works

In any client, ask: "What tools does agent-cost expose?" — you should see eleven tool names grouped roughly like this:

• cost queries: get_session_cost, get_tool_usage, get_cost_trend, get_subagent_tree
• optimization analytics: get_tool_roi, suggest_optimizations, detect_cost_anomalies
• predictive: get_cost_forecast, estimate_run_cost
• configuration: configure_budget, set_monitor_webhook

If nothing shows up, see the FAQ.

Marketplace / Discovery

Current verified discovery surfaces:

• npm: canonical install path via npx -y @vk0/agent-cost-mcp
• MCP Registry: package metadata and registry-facing identity
• Smithery: verified live third-party listing at https://smithery.ai/servers/unfucker/agent-cost-mcp
• mcp.so: verified live product page at https://mcp.so/server/agent-cost-mcp/vk0dev

Glama should be treated as unverified for now until its stable product-page URL is re-confirmed.

Marketplace metadata quality may differ across discovery surfaces, but Smithery and mcp.so currently have verified live presence for this package. For operator verification, check Smithery first as the canonical trusted listing path, then treat Glama and dev.tools as manual re-check surfaces rather than assumed live listings.

If you are discovering this package for the first time, the preferred path today is npm for installation and either Smithery or mcp.so for marketplace-style browsing.

Quick visibility (native /cost, ccusage, cctally) vs Cost Guard forensics (@vk0/agent-cost-mcp)

Claude Code, ccusage, and cctally already give you useful cost visibility. @vk0/agent-cost-mcp is for the next layer: forensics, attribution, and guardrails.

Use native /cost, ccusage, or cctally when

• you want a quick current-session total or statusline number
• you need daily or period usage dashboards or burn-rate summaries
• you want Pro/Max subscription-quota forecasts, cost-per-percent trends, or threshold alerts (cctally)
• you are looking for a polished human-facing monitoring UX
• nothing to configure

Use @vk0/agent-cost-mcp when

• you want per-tool cost share and ROI ranking with get_tool_roi and get_tool_usage
• you need parent↔subagent cost attribution across branches with get_subagent_tree
• you want anomaly detection against your local baseline with detect_cost_anomalies
• you need forward-looking spend estimates from get_cost_forecast or estimate_run_cost
• you want agent-readable budget caps and hard-stop guardrails via configure_budget
• you need machine-readable next-action suggestions and signed webhook alerts via suggest_optimizations and set_monitor_webhook

Best together

Use native /cost, ccusage, or cctally for quick visibility; reach for @vk0/agent-cost-mcp when the next question is: which tool, subagent, or branch burned the budget, what happens if the run continues, and what should the agent do next? — answered locally from JSONL, machine-readable.

This package does not replace invoices, org-wide billing systems, or live runtime introspection. It is a local MCP surface for structured cost forensics and guardrails from Claude Code session logs.

Docs and how-to guides

If you want concrete operator workflows instead of the full reference, start here:

• Need quick recipes for setup, forecast, and budget-cap workflows? See docs/README.md
• Latest shipped release note: 2.3.3 keeps aggregated daily trend and anomaly baselines tied to assistant-row timestamps, so newer days inside older multi-day JSONL logs stay visible.
• If spend is split across parent and child sessions and you need the nested subtreeCost story, open docs/subagent-tree-guide.md
• Quick setup with Claude Desktop
• How to read a get_subagent_tree output
• Budget cap recipe: when to use 80% soft alert vs 100% hard cap

Already-shipped demo assets you can inspect quickly:

• Forecast / cap-hit demo GIF for the current get_cost_forecast operator story
• Subagent-tree cost demo GIF for the current get_subagent_tree branch-cost story

Tools