agent-cost-mcp

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

Current v2.3.2 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.2, 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 and ccusage for quick visibility — totals, statusline, daily usage. 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.2, 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) vs Cost Guard forensics (@vk0/agent-cost-mcp)

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

Use native /cost or ccusage when

• you want a quick current-session total or statusline number
• you need daily or period usage dashboards or burn-rate summaries
• 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 or ccusage 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.2 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

Eleven MCP tools, all operating on local JSONL session logs and all aimed at one Cost Guard question: where is spend accumulating, how risky is the current pattern, and what should the operator or agent change next?

Cost queries (read-only):

Optimization analytics:

Predictive (pre-spend):

| estimate_run_cost | Estimate the likely cost of a planned run before execution from prompt, model, and expected tool-call shape, returning {low, expected, high} with confidence for pre-spend decisions. |

Configuration (write):

| set_monitor_webhook | Register an HMAC-signed webhook target for anomaly alerts, budget threshold crossings, and runaway flags so Cost Guard signals can leave the local session and reach an operator workflow when needed. |

Monitor alerts do not work until set_monitor_webhook has saved both the webhook URL and secret in the local monitor config at ~/.agent-cost-mcp/monitor-webhook.json.

For a quick local test, start a tiny localhost receiver first, then point set_monitor_webhook at http://127.0.0.1:8787/hook:

python3 - <<'PY'
from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("content-length", "0"))
        body = self.rfile.read(length).decode("utf-8", errors="replace")
        print(f"\n--- webhook {self.path} ---")
        print(body)
        self.send_response(204)
        self.end_headers()

HTTPServer(("127.0.0.1", 8787), Handler).serve_forever()
PY

On Windows, use the same local listener idea with py -3 if python3 is not the Python launcher on your machine.

{
  "sessionPath": "~/.claude/projects/my-project/session-main.jsonl",
  "subagentPaths": [],
  "turnCount": 2,
  "totals": {
    "input_tokens": 2000,
    "output_tokens": 500,
    "cache_read_input_tokens": 100,
    "cache_creation_input_tokens": 50,
    "tool_use_count": 1,
    "tool_result_count": 1,
    "linked_tool_result_count": 1,
    "estimated_cost_usd": 0.013718
  }
}

{
  "projectPath": "~/.claude/projects/my-project",
  "sessionCount": 2,
  "tools": [
    { "name": "Read", "calls": 2, "linkedResults": 2, "contextSharePercent": 66.67 },
    { "name": "Grep", "calls": 1, "linkedResults": 0, "contextSharePercent": 33.33 }
  ]
}

{
  "projectPath": "~/.claude/projects/my-project",
  "days": 7,
  "totalCostUsd": 0.027443,
  "totalSessions": 2,
  "daily": [
    {
      "date": "2026-04-10",
      "sessions": 2,
      "costUsd": 0.027443,
      "inputTokens": 2400,
      "outputTokens": 600
    }
  ]
}

{
  "sessionPath": "~/.claude/projects/my-project/session-main.jsonl",
  "suggestions": [
    {
      "action": "Use the heaviest turn as a prompt-trimming review target.",
      "reason": "Turn 1 is the densest token consumer in this session.",
      "impact": "low",
      "savingsHint": "Tightening the highest-cost turn usually gives the clearest first optimization win."
    }
  ]
}

Example conversation

You:   How much did I spend on Claude Code this week?

Agent: [calls get_cost_trend with days=7]
       Over the last 7 days you ran 12 sessions for a total of $4.82.
       Heaviest day was Wednesday at $1.47 across 4 sessions.

You:   Which tools are eating my context?

Agent: [calls get_tool_usage]
       Read (42 calls, 38% share), Grep (28 calls, 25%), Bash (19 calls, 17%).
       Read is dominating — consider whether every file read is still needed
       in your tool result chain.

You:   Any quick wins for my last session?

Agent: [calls suggest_optimizations]
       1. Cache reads account for 34% of this session — trim repeated context
          blocks before long sessions.
       2. 7 tool calls had no linked results — inspect abandoned invocations.

How it works

  ~/.claude/projects/*.jsonl           ┌─────────────────┐
  (Claude Code session logs)  ──────▶  │  JSONL parser   │
                                       │  + pricing.ts   │
                                       └────────┬────────┘
                                                │
                                                ▼
                                       ┌──────────────────────────┐
  Agent tool call (stdio MCP)  ──────▶ │  MCP server              │ ─── JSON response
                                       │  (11 tools across query, │
                                       │   analytics, forecast,   │
                                       │   and config surfaces)   │
                                       └──────────────────────────┘

• Parser reads per-turn usage fields (input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens) directly from the raw JSONL lines produced by Claude Code.
• Pricing table (src/pricing.ts) holds per-million-token rates for Claude models, with a default fallback so unknown models still render a summary instead of failing.
• MCP server exposes eleven typed tools over stdio, covering local cost queries, per-tool/session analytics, anomaly detection, pre-run forecasting, budget caps, and webhook alert configuration.
• Zero network egress by default. No telemetry, no API key, no cloud sync. The only optional outbound surface is set_monitor_webhook, which is explicit opt-in configuration for alert delivery.

Comparison vs alternatives

These tools overlap, but they optimize for different questions. The short version: if you want a local MCP-first Cost Guard that an agent can query directly for session forensics, per-tool attribution, forecasts, anomalies, and guardrails, @vk0/agent-cost-mcp is the narrow fit. If you mainly want a dashboard, a native quick check, or a general burn monitor, one of the alternatives may be the better first stop.

A few honest caveats:

• Built-in /cost or /usage is still the best answer if all you want is a quick native number.
• ccusage, claude-usage, or Claude-Code-Usage-Monitor may be the better choice if your main priority is a reporting-first or monitor-first experience rather than deeper session forensics.
• CodeBurn may be the better fit if burn-rate monitoring matters more than local cost debugging detail.
• @vk0/agent-cost-mcp is intentionally narrower: local Claude Code JSONL logs, pricing-aware cost analysis, MCP-callable outputs, and guardrail-style answers inside the agent loop.

Best fit: solo developers and small teams who want an agent to answer “where did my tokens go, which tool or branch caused it, is this pattern risky, and what should I change next?” without sending logs to a cloud service or opening a separate billing dashboard.

FAQ

Limitations

• Estimates, not billing. Costs are derived from per-turn usage fields × a local pricing table. Not a substitute for your Anthropic invoice.
• Pricing table is manual. src/pricing.ts must be updated when rates change (by design — no silent network calls).
• Claude Code only. Cursor/Cline/Continue sessions are not parsed. Other clients may be added if there is demand.
• Local file discovery. The server reads files from a project path you provide. It does not query a live Claude Code runtime state.
• Structured JSON output. No rich dashboards, no charts, no web UI. That is a feature, not a bug — the MCP client is the UI.
• Cache-read awareness depends on source. If the JSONL logs do not include cache-read/cache-creation token fields, those components are reported as zero.

Standalone CLI

The same parser is exposed as a CLI for one-off analysis without an MCP client:

npx -y @vk0/agent-cost-mcp ~/.claude/projects/my-project/session.jsonl
npx -y @vk0/agent-cost-mcp session.jsonl --subagent subagent.jsonl
npx -y @vk0/agent-cost-mcp session.jsonl --watch --watch-interval 5

--watch keeps re-scanning the target session log on an interval and prints the refreshed compact summary, which is useful while an active coding session is still accumulating cost.

Outputs the same JSON the MCP get_session_cost tool returns.

Development

Clone the repo and run:

npm ci           # install deps
npm run build    # compile to dist/
npm test         # vitest unit tests
npm run lint     # tsc --noEmit
npm run smoke    # end-to-end MCP client smoke test

Stack: TypeScript, @modelcontextprotocol/sdk, Zod, Vitest.

Official MCP Registry recovery path

If npm/package metadata is already correct but the Official MCP Registry listing needs a bounded re-publish, trigger the dedicated GitHub Actions workflow instead of creating a new tag or rerunning the full release flow:

gh workflow run registry-republish.yml --repo vk0dev/agent-cost-mcp

This workflow republishes server.json to the Official MCP Registry via GitHub OIDC only. It does not publish to npm and does not create a new release.

Changelog

See CHANGELOG.md. This project follows semantic versioning from v1.0.0 onwards.

Contributing

Issues and PRs welcome at github.com/vk0dev/agent-cost-mcp. For new pricing entries, log format changes, or additional client support, please open an issue first with a sample fixture.

License

MIT © vk0.dev