mcp-cost-tracker-router

MCP 成本跟踪与路由

npm mcp-cost-tracker-router 包

面向 MCP Agent 工作流，本地优先的成本监控。使用 js-tiktoken 离线计算 Token 数量，无需代理、无需 API 往返，也不会将支出数据传出你的设备。成本升高时，路由建议会在账单到来前为你推荐更便宜的模型。

工具参考 | 配置 | 贡献 | 故障排查

主要功能

• 按工具细分成本：准确查看哪些工具调用消耗的 Token 和预算最多。
• 预算提醒：设置会话支出阈值，在达到阈值的 80% 和 100% 时收到提醒，避免超支。
• 离线 Token 计数：使用 js-tiktoken 准确计数，无需 API 调用。
• 模型路由建议：根据当前任务类型推荐更便宜的模型（仅供参考，未经选择启用时绝不会强制执行）。
• 多提供商定价：通过一张可配置的定价表跟踪 Claude、OpenAI 和 Gemini 模型的成本。
• 支出历史记录：按模型或工具查询每日、每周和每月总额。
• 项目成本分摊：将会话标记为指定项目，并生成费用分摊报告。
• HTML 支出报告：导出包含图表和预算状态的独立、自包含 HTML 报告。
• 审计日志：以追加方式记录每项预算执行决策。

为什么选择它，而不是基于代理的成本跟踪工具？

大多数成本跟踪工具会将所有 API 流量经由其服务转发，并在服务端统计 Token。这意味着你的提示词和回复会经过第三方服务，而且你需要依赖该服务的正常运行。

	mcp-cost-tracker-router	基于代理的跟踪工具（Helicone、LLMonitor 等）
Token 计数	通过 js-tiktoken 离线计数，无网络调用	流量经由代理后在服务端计数
数据驻留	仅存储在本地 SQLite	提示词和回复会经过供应商服务器
模型路由	内置 suggest_model_routing 工具	很少包含；通常是单独的付费套餐
多提供商支持	Claude、OpenAI、Gemini 共用一张定价表	通常仅支持单一提供商，或需要单独配置
运行时间依赖	无，完全离线	代理服务宕机时会中断

如果你的提示词包含敏感信息，或者你无法将流量经由第三方转发，那么这款工具正适合你。如果你需要支持团队共享的托管式仪表板，基于代理的服务可能更适合。

免责声明

mcp-cost-tracker-router 会在本地 SQLite 中存储工具调用元数据（Token 数量、模型名称、时间戳）。它不会存储提示词或回复内容。成本计算基于本地定价表进行估算，可能与提供商账单不完全一致。

要求

• Node.js v20.19 或更高版本。
• npm。

开始使用

将以下配置添加到 MCP 客户端：

{
  "mcpServers": {
    "cost-tracker": {
      "command": "npx",
      "args": ["-y", "mcp-cost-tracker-router@latest"]
    }
  }
}

设置会话预算提醒：

{
  "mcpServers": {
    "cost-tracker": {
      "command": "npx",
      "args": ["-y", "mcp-cost-tracker-router@latest", "--budget-alert=5.00"]
    }
  }
}

MCP 客户端配置

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

你的第一个提示词

在 MCP 客户端中输入以下内容，验证一切是否正常运行：

How much has this session cost so far?

客户端应返回当前会话的 Token 数量和 USD 成本摘要。

工具

会话（4 个工具）

• get_session_cost — 返回当前会话的 Token 总数和 USD 成本估算。只读。
• get_tool_costs — 返回会话的按工具细分成本，按成本降序排列。只读。
• reset_session — 开始新的成本跟踪会话。之前的会话数据会保留在历史记录中。
• record_usage — 记录一次工具调用的 Token 使用量。接受 tool_name、model（可选）、input_tokens 和 output_tokens。达到阈值的 80% 时会发出预算警告通知。

预算与路由（3 个工具）

• set_budget_alert — 设置以美元计的预算阈值（threshold_usd）。在达到阈值的 80% 和 100% 时发出警告。搭配 --enforce-budget 使用，可阻止超出限额的调用。
• suggest_model_routing — 根据任务类型启发式推荐模型。接受 task_description 和可选的 constraints.max_cost_usd。返回推荐模型、推荐理由和预估费用。
• check_routing_policy — 检查指定模型是否符合路由策略，可用于指定任务类型。接受 task_type 和 model。

历史记录与报告（4 个工具）

• get_spend_history — 按 period（day/week/month）汇总查询历史支出。返回按模型和工具划分的明细。只读。
• estimate_workflow_cost — 预估多步骤工作流的运行前费用。接受包含 tool_name、estimated_input_tokens、estimated_output_tokens 和可选 model 的 steps 数组。只读。
• export_spend_report — 生成单文件 HTML 支出报告，包含会话明细、历史支出、模型费用对比和预算状态。只读。
• export_budget_audit — 导出预算执行决策的审计日志。接受可选的 from_date、to_date 和 format（json/csv）。只读。

项目分配（4 个工具）

• set_project — 创建或更新项目，可选设置 budget_usd。接受 project_name。
• tag_session — 使用 project_name 为当前会话添加标签，以便分配费用。
• get_project_costs — 获取项目费用报告。接受 project_name 和可选的 since（ISO 日期）。只读。
• export_chargeback — 生成内部计费所用的分摊报告。接受 from_date、to_date、可选的 group_by（project/session）和可选的 format（json/csv）。只读。

配置

--budget-alert

以美元计的会话支出阈值。当会话费用达到此阈值的 80% 和 100% 时，将分别返回警告。

类型：number

--db / --db-path

用于存储费用历史记录的 SQLite 数据库文件路径。

类型：string 默认值：~/.mcp/costs.db

--pricing-table

包含自定义模型定价（每 1K 个 token 的费用）的 JSON 文件路径。与内置定价表合并；未列出的模型使用默认价格。

类型：string

--default-model

无法从上下文推断模型时，用于归属费用的模型名称。

类型：string 默认值：claude-sonnet-4-6

--enforce-budget

阻止会导致会话费用超出预算警告阈值的工具调用。需要设置 --budget-alert。

类型：boolean 默认值：false

--http-port

使用 Streamable HTTP 传输而非 stdio，以 HTTP 模式启动。适用于团队共享单个费用跟踪实例。

类型：number 默认值：已禁用（使用 stdio）

通过 JSON 配置中的 args 属性传递标志：

{
  "mcpServers": {
    "cost-tracker": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-cost-tracker-router@latest",
        "--budget-alert=2.00",
        "--enforce-budget"
      ]
    }
  }
}

支持的模型与定价

内置定价表（每 1K 个 token 的美元价格）：

模型	输入	输出
claude-opus-4-6	$0.0150	$0.0750
claude-sonnet-4-6	$0.0030	$0.0150
claude-haiku-4-5	$0.0008	$0.0040
gpt-4o	$0.0025	$0.0100
gpt-4o-mini	$0.000150	$0.000600
gemini-1.5-pro	$0.001250	$0.005000
gemini-1.5-flash	$0.000075	$0.000300
gemini-2.0-flash	$0.000100	$0.000400

使用 --pricing-table 覆盖单个模型的价格。所有费用均为估算值。

验证

发布新版本前，使用 MCP Inspector 验证服务，确认所有工具均已正确公开，且协议握手成功。

交互式 UI（打开浏览器）：

npm run build && npm run inspect

CLI 模式（适合脚本 / CI）：

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a read-only tool
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name get_session_cost

# Call record_usage with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name record_usage \
  --tool-arg tool_name=my_tool --tool-arg input_tokens=500 --tool-arg output_tokens=200

发布前运行此项，以发现工具注册和运行时启动方面的回归问题。

贡献

发布新模型时，请更新 src/pricing.ts。所有成本计算变更都必须包含单元测试，并使用已知的 token 数量和预期的 USD 值。路由建议位于 src/tools/routing.ts。

npm install && npm test

MCP Registry & Marketplace

此插件可在以下平台使用：

• MCP Registry
• MCP Market

搜索 mcp-cost-tracker-router。