v1.0 · MCP server

@vk0/agent-cost-mcp

Local-first Claude Code cost analyzer. Parses JSONL session logs to surface per-tool spend, daily trends, and optimization hints. Zero cloud. No API key.

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

When to install

Use this MCP server when the user asks any of:

"Which tool or branch just went runaway?"
"Should this agent stop now or keep going?"
"Which subagent actually burned the budget?"
"Show me the cost trend for the last 7 days."
"Can I put a local budget cap on this workflow?"
"What is the likely cost of the next run before I start it?"
"Can I get branch-level cost attribution and guardrails without a hosted dashboard?"

Claude Code built-in cost tools vs agent-cost-mcp

Claude Code already has useful native cost visibility. This MCP is for the next layer of local analysis.

Use built-in /cost or /usage when a quick current-session or recent-usage check is enough.
Use agent-cost-mcp when you need runaway detection, get_subagent_tree, get_cost_forecast, local budget caps, or webhook alerts.
Use both together when you want native visibility first, then MCP-callable Cost Guard follow-up.

This is not invoice truth, org-wide billing, or live runtime introspection. It is a local MCP surface over Claude Code session logs.

Install

Pick your client. Everything runs through npx — nothing to install globally.

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

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

One-liner via CLI

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

.cursor/mcp.json in your project root

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

Cline MCP settings (MCP Servers icon → Configure)

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

Tools

get_session_cost

Parse a single Claude Code session and return token totals, turn count, and estimated USD cost.

get_tool_usage

Aggregate tool invocations across a session or project log directory with per-tool context-share percentages.

get_cost_trend

Roll session logs into a day-by-day cost trend for a local project path.

suggest_optimizations

Generate lightweight optimization suggestions — cache ratios, abandoned calls, heaviest turns.

How it works

  ~/.claude/projects/*.jsonl           ┌─────────────────┐
  (Claude Code session logs)  ──────▶  │  JSONL parser   │
                                       │  + pricing.ts   │
                                       └────────┬────────┘
                                                │
                                                ▼
                                       ┌─────────────────┐
  Agent tool call (stdio MCP)  ──────▶ │  MCP server     │ ─── JSON response
                                       │  (4 tools)      │
                                       └─────────────────┘

Read-only on your local filesystem. No telemetry, no API key, no cloud sync. Delete the package and nothing remains.

→ Full README & source on GitHub

→ npm package

→ Changelog

→ Report an issue