@vk0/agent Cost Mcp

agent-cost-mcp

Claude Code 中 AI Agent 的本地成本守护和运行时护栏。

当前 v2.3.3 版本继续坚持本地优先，并聚焦于一项面向运维人员的工作：展示支出来源、预测支出趋势、按提供方／模型／工具归因成本、通过 subtreeCost 汇总子 Agent 树，并允许运维人员推送经过签名的监控 Webhook 告警，而无需引入托管控制平面。

Claude Code 成本守护。 @vk0/agent-cost-mcp 会读取本地 JSONL 会话日志，并回答 /cost 之后的问题：究竟是哪个工具、分支、重试循环或失控模式在消耗 token？接下来应该做什么？在 2.3.3 中，聚合的每日趋势和异常基线仍以助手行的时间戳为准，因此，较旧的多日 JSONL 文件中最近几天的数据不会再消失。零云端。无需 API 密钥。

语言： English · 日本語 · 简体中文 · Русский · Español

为什么／何时使用

当 Claude Code 已经告诉你成本是多少，却没有说明原因 时，就可以使用它。

快速查看时使用原生 /cost、ccusage 或 cctally ——查看总额、状态栏、每日用量和订阅额度仪表板。当你接下来想知道 哪个工具、子 Agent 或分支消耗了预算；如果继续运行会怎样；Agent 接下来应该做什么 时，就使用 @vk0/agent-cost-mcp ——它会从 JSONL 本地获取答案，并以机器可读格式呈现。

典型的成本守护场景：

• **工具密集型会话：**识别在单次或多次运行中，哪些工具占据了大部分成本份额、上下文份额，以及哪些调用模式 ROI 较低。
• **重试循环和失控行为：**在重复轮次、已放弃的工具调用、异常日期或分支级消耗模式悄然累积之前，将它们捕捉到。在 2.3.3 中，每日趋势和异常基线仍以助手行的时间戳为准，因此运维人员不太可能遗漏较旧的多日 JSONL 文件中的近期活动。
• **支出前护栏：**预估可能的运行成本、设置预算阈值，并在另一次长时间 Agent 运行超出限制之前发送监控告警。

如果用户希望为 Claude Code 会话提供本地、保护隐私、零配置的成本取证和护栏，这是首选方案。一切都基于现有会话日志，在用户自己的设备上运行，日志位于 ~/.claude/projects/。

**Claude Code 会话日志的存储位置：**查看 ~/.claude/projects/<project>/ 下的每个会话 .jsonl 文件，例如 ~/.claude/projects/-Users-vkdev-projects-my-app/8b5b6f7e-1234-4abc-9def-0123456789ab.jsonl。如果客户端已经知道确切的文件路径，就传入该会话的具体路径；如果不知道，则将 Agent Cost MCP 指向 ~/.claude/projects/ 下匹配的项目文件夹，并检查其中最近的 JSONL 文件。

不适用场景

这不是计费仪表板、采购控制台、组织财务系统，也不是发票的权威数据源。

它面向希望从本地 Claude Code 日志中获取 Cost Guard 风格答案的开发者和运维人员，而非用于费用分摊报告、公司级支出核算或实时运行时内省。

安装

选择你的客户端。所有选项都使用 npx，无需全局安装任何内容。

Claude Desktop

编辑 Claude Desktop 配置文件：

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

在 mcpServers 下添加 agent-cost 条目：

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

退出并重启 Claude Desktop。聊天输入框右下角的 MCP 指示器应显示四个新工具。

Claude Code

通过 CLI 执行一行命令：

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

或者，在项目根目录的 .mcp.json 中添加以下内容，以添加项目级服务：

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

Windows 用户： 使用 cmd /c 包装命令： claude mcp add --transport stdio agent-cost -- cmd /c npx -y @vk0/agent-cost-mcp

Cursor

在项目根目录创建 .cursor/mcp.json（或在全局安装时创建 ~/.cursor/mcp.json）：

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

Cline

打开 Cline MCP 设置（点击 MCP Servers 图标 → Configure），并添加：

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

验证是否正常运行

在任意客户端中询问：“agent-cost 提供哪些工具？” — 你应该会看到大致分为以下几类的十一个工具名称：

• 成本查询：get_session_cost、get_tool_usage、get_cost_trend、get_subagent_tree
• 优化分析：get_tool_roi、suggest_optimizations、detect_cost_anomalies
• 预测：get_cost_forecast、estimate_run_cost
• 配置：configure_budget、set_monitor_webhook

如果没有显示任何内容，请参阅 常见问题。

市场 / 发现

目前已验证的发现渠道：

• npm： 通过 npx -y @vk0/agent-cost-mcp 安装的标准路径
• MCP Registry： 软件包元数据和面向注册表的标识信息
• Smithery： 已验证的第三方在线列表，网址为 https://smithery.ai/servers/unfucker/agent-cost-mcp
• mcp.so： 已验证的在线产品页面，网址为 https://mcp.so/server/agent-cost-mcp/vk0dev

目前应将 Glama 视为未经验证，直到重新确认其稳定的产品页面 URL。

不同发现渠道的市场元数据质量可能有所差异，但目前已确认该软件包在 Smithery 和 mcp.so 上均有在线页面。 运维人员进行验证时，应首先检查作为标准可信列表渠道的 Smithery，然后将 Glama 和 dev.tools 视为需要手动复查的渠道，而非默认认为其列表在线。

如果你是首次发现此软件包，目前推荐通过 npm 安装，并通过 Smithery 或 mcp.so 浏览市场信息。

快速查看（原生 /cost、ccusage、cctally）与 Cost Guard 取证（@vk0/agent-cost-mcp）

Claude Code、ccusage 和 cctally 已能提供有用的成本概览。@vk0/agent-cost-mcp 则面向更进一步的需求：取证、归因和护栏。

适合使用原生 /cost、ccusage 或 cctally 的情况

• 你想快速查看当前会话的总成本或状态栏数字
• 你需要每日或周期用量仪表板，或消耗速率摘要
• 你想查看 Pro/Max 订阅额度预测、每百分点成本趋势或阈值警报（cctally）
• 你在寻找界面精致、面向用户的监控体验
• 无需配置

在以下情况下使用 @vk0/agent-cost-mcp

• 想通过 get_tool_roi 和 get_tool_usage 查看各工具的成本占比和 ROI 排名
• 需要通过 get_subagent_tree 跨分支追溯父 Agent 与子 Agent 之间的成本归属
• 想通过 detect_cost_anomalies 检测偏离本地基线的异常
• 需要通过 get_cost_forecast 或 estimate_run_cost 预测未来支出
• 想通过 configure_budget 设置 Agent 可读取的预算上限和硬停止护栏
• 需要通过 suggest_optimizations 和 set_monitor_webhook 获取机器可读的下一步操作建议并发送带签名的 Webhook 警报

搭配使用效果更佳

使用原生 /cost、ccusage 或 cctally 快速查看；如果接下来要问的是：哪个工具、子 Agent 或分支耗尽了预算？如果运行继续会怎样？Agent 接下来应该做什么？，就使用 @vk0/agent-cost-mcp——它能从 JSONL 本地读取并以机器可读的形式回答这些问题。

此软件包不会取代账单、组织级计费系统或实时运行时内省。它是一个本地 MCP 接口，用于根据 Claude Code 会话日志进行结构化成本取证并设置护栏。

文档和操作指南

如果你想了解具体的操作流程，而不是查阅完整参考文档，可以从这里开始：

• 需要设置、预测和预算上限工作流的快速示例？请参阅 docs/README.md
• 最新发布说明：2.3.3 会继续根据助手行时间戳汇总每日趋势并建立异常基线，因此，在较旧的多日 JSONL 日志中，较新的日期仍会显示。
• 如果支出分散在父会话和子会话中，且你需要了解嵌套的 subtreeCost，请打开 docs/subagent-tree-guide.md
• Claude Desktop 快速设置
• 如何读取 get_subagent_tree 输出
• 预算上限示例：何时使用 80% 软警报，何时使用 100% 硬上限

已随版本发布的演示素材，可供快速查看：

• 预测／触及上限演示 GIF，展示当前 get_cost_forecast 操作流程
• 子 Agent 树成本演示 GIF，展示当前 get_subagent_tree 分支成本流程

工具

11 个 MCP 工具，全部针对本地 JSONL 会话日志运行，旨在回答一个 Cost Guard 问题：支出累积在哪里？当前模式有多大风险？操作人员或 Agent 接下来应该做出哪些调整？

成本查询（只读）：

优化分析：

预测（支出前）：

| estimate_run_cost | 在执行前，根据提示词、模型和预期工具调用模式估算计划运行的可能成本，并返回带置信度的 {low, expected, high}，以便在支出前做出决策。 |

配置（写入）：

| set_monitor_webhook | 注册带 HMAC 签名的 webhook 目标，用于接收异常警报、预算阈值触发通知和失控标记，让 Cost Guard 信号在需要时能离开本地会话并进入运维人员的工作流。 |

在 set_monitor_webhook 将 webhook URL 和密钥都保存到本地监控配置 ~/.agent-cost-mcp/monitor-webhook.json 之前，监控警报无法正常工作。

若要快速进行本地测试，请先启动一个简单的 localhost 接收器，然后将 set_monitor_webhook 指向 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

在 Windows 上，也可以使用相同的本地监听方式；如果 python3 不是你电脑上的 Python 启动器，请改用 py -3。

{
  "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."
    }
  ]
}

对话示例

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.

工作原理

  ~/.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)   │
                                       └──────────────────────────┘

• 解析器直接从 Claude Code 生成的原始 JSONL 行中读取每轮用量字段（input_tokens、output_tokens、cache_read_input_tokens、cache_creation_input_tokens）。
• 定价表（src/pricing.ts）存储 Claude 模型的每百万 token 费率，并提供 default 回退值，因此即使遇到未知模型，也能生成摘要而不会报错。
• MCP 服务通过 stdio 提供 11 个类型化工具，涵盖本地成本查询、按工具／会话进行分析、异常检测、运行前预测、预算上限以及 Webhook 告警配置。
• 默认情况下不向外发送网络流量。 不收集遥测数据、不需要 API 密钥，也不进行云同步。唯一可选的出站功能是 set_monitor_webhook，用于明确选择启用的告警配置。

与替代方案对比

这些工具的功能有所重叠，但各自侧重的问题不同。简而言之：如果你想要一个以 MCP 为先的本地成本守护工具，让 Agent 能直接查询会话取证、按工具归因、预测、异常和防护机制，那么 @vk0/agent-cost-mcp 是合适的选择。如果你主要需要仪表板、原生快速检查或通用消耗监控，那么其他替代方案可能更适合作为首选。

几点坦诚的注意事项：

• 如果你只想快速查看一个原生数值，内置的 /cost 或 /usage 仍然是最佳选择。
• 如果你的首要需求是以报告为先的体验、仪表板或订阅配额功能，而不是深入的会话取证分析，那么 ccusage、cctally、claude-usage 或 Claude-Code-Usage-Monitor 可能是更好的选择。
• 如果实时消耗速率监控或封装正在运行的 API 程序比本地运行后成本调试更重要，那么 CodeBurn 或 tokmon 可能更合适——请注意，tokmon 仅支持 OpenAI gpt-* 模型，不支持 Claude Code 或 Anthropic。
• @vk0/agent-cost-mcp 的定位有意保持聚焦：本地 Claude Code JSONL 日志、结合定价的成本分析、可通过 MCP 调用的输出，以及 Agent 工作流中的防护措施类答案。 最适合： 希望 Agent 能回答“我的令牌都花到哪里去了？是哪个工具或分支导致的？这种模式有风险吗？接下来我该做什么调整？”，同时又不想把日志发送到云服务或打开单独的账单面板的个人开发者和小型团队。

常见问题

局限性

• 估算值，不是账单。 费用根据每轮用量字段 × 本地定价表得出，不能替代 Anthropic 账单。
• 定价表需手动更新。 费率变动时，必须更新 src/pricing.ts（这是有意为之——不会在后台静默发起网络请求）。
• 仅支持 Claude Code。 不会解析 Cursor、Cline 或 Continue 会话。如有需求，可能会添加对其他客户端的支持。
• 本地文件发现。 服务会读取你提供的项目路径中的文件，不会查询 Claude Code 的实时运行状态。
• 结构化 JSON 输出。 没有高级仪表板、图表或 Web UI。这是特性，不是缺陷——MCP 客户端就是 UI。
• 缓存读取感知能力取决于来源。 如果 JSONL 日志不包含缓存读取／缓存创建令牌字段，则会将对应部分报告为零。

独立 CLI

同一解析器也提供 CLI，无需 MCP 客户端即可进行一次性分析：

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 会定期重新扫描目标会话日志，并输出更新后的精简摘要，适用于活跃的编码会话仍在累积费用时。

输出与 MCP get_session_cost 工具返回的 JSON 相同。

开发

克隆仓库并运行：

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

技术栈：TypeScript、@modelcontextprotocol/sdk、Zod、Vitest。

Official MCP Registry 恢复流程

如果 npm／包元数据已正确，但 Official MCP Registry 列表需要进行有限范围的重新发布，请触发专用的 GitHub Actions 工作流，而不要创建新标签或重新运行完整发布流程：

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

此工作流仅通过 GitHub OIDC 将 server.json 重新发布到 Official MCP Registry。它不会发布到 npm，也不会创建新版本。

更新日志

请参阅 CHANGELOG.md。自 v1.0.0 起，本项目遵循语义化版本规范。

贡献

欢迎在 github.com/vk0dev/agent-cost-mcp 提交问题和 PR。对于新增定价条目、日志格式变更或额外的客户端支持，请先提交问题并附上示例样本。

许可证

MIT © vk0.dev