agent-cost-mcp-server

Agent Cost MCP Server

一个 MCP 服务，为 Agent 和开发者提供工具，让他们能够在运行前和运行期间估算、规划预算并比较大模型任务的成本——相当于 AWS 基础设施成本工具中的模型支出计算器。

Agent 框架会自行决定一项任务需要进行多少次模型调用，因此一次运行的成本通常要等账单寄达后才会显现。这个服务让你可以在自己的工具中直接解答：

• 这项任务使用模型 A 和模型 B，成本分别是多少？
• 哪个模型的单项成功任务成本最低，而不是每个令牌的成本最低？
• 这次运行是否已经超出预算？

这个服务自成一体：内置持续维护的定价快照，无需 AWS 账户或 API 密钥，所有状态都保存在本地 JSON 账本中，运行时不会发起网络请求。

演示

一次实时 MCP 客户端会话（2026 年 11 月 9 日）：客户端通过 stdio 连接，列出 5 个工具，将一次 Sonnet 4.5 运行的成本定为 $0.063，按单项成功任务成本重新排列模型排名，向账本记录两笔支出，并检查任务是否超出预算——已花费 $0.0784，预算为 $0.10。完整的会话输出及其写入的账本见 demo/。

适用对象

• tokenecon — 此服务基于 tokenecon 的成本模型构建；compare_models_for_task 是其按正确结果成本进行排序的功能，并以工具形式开放，可供 Agent 在运行过程中调用。
• Argus — 负责执行策略的配套项目：此服务通过 MCP 工具提供数据，而 Argus 在网关层执行策略和预算；在 Argus Chat 中，每个经由 Argus 提供的回答都附带 tokenecon 收据。
• mcplens — 负责审核的配套项目：在信任任何 MCP 服务之前，mcplens 会根据其描述所声称的功能，对其实际行为进行评估。

彼此关联的工具集 — 一条贯穿所有项目的线索：Agent 做了什么、花费了多少，以及是否应该允许它这么做。Argus · tokenecon · mcplens · agent-cost-mcp-server · Argus Lens · PersistAIBench · Argus-Bench

工具

工具	参数	返回值
price_usage	model_id、input_tokens、output_tokens	一条具体用量记录的输入、输出和总费用（美元）
estimate_run_cost	model_id、input_tokens、output_tokens	该模型单次运行的费用，以及在其他所有模型上为相同工作负载计算的费用，按价格从低到高排列
compare_models_for_task	input_tokens、output_tokens、success_rates?	按预期的每项成功任务费用排列的所有模型（每次尝试费用 ÷ 成功率）
record_spend	task_id、model_id、input_tokens、output_tokens	按标价计费的账本记录
budget_status	task_id、budget_usd	该任务的 {spent_usd, remaining_usd, over_budget, calls, models_used, by_model}。by_model 将每个 model_id 映射到 {calls, input_tokens, output_tokens, spent_usd}

按每个 token 的成本排名并不适用于 Agent 工作：一种便宜但有一半任务会失败的模型，其每项成功任务的成本会高于一种价格更高但更可靠的模型。如果有测得的成功率，请将其传给 compare_models_for_task；未提供成功率的模型会按原始成本排名。

此服务提供相关数据。强制执行预算（停止运行）属于 Agent 框架的职责——请参阅 strands-agents/samples 中的 BudgetedModel 了解这种模式。

安装

此服务已发布到 PyPI（当前版本为 0.1.1），并列入 Official MCP Registry，条目为 io.github.karmendra8386/agent-cost-mcp-server。需要 Python 3.10+； 使用 uvx 方式需要安装 uv。

Claude Code

claude mcp add agent-cost -- uvx agent-cost-mcp-server

Claude Desktop 和 Cursor

添加到客户端的 MCP 配置中（Claude Desktop： claude_desktop_config.json；Cursor：.cursor/mcp.json）：

{
  "mcpServers": {
    "agent-cost": {
      "command": "uvx",
      "args": [
        "agent-cost-mcp-server"
      ]
    }
  }
}

VS Code

添加到 .vscode/mcp.json（VS Code 使用 servers 键）：

{
  "servers": {
    "agent-cost": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "agent-cost-mcp-server"
      ]
    }
  }
}

pip

pip install agent-cost-mcp-server
agent-cost-mcp-server   # serves over stdio

从源码安装（GitHub）

如果需要 master 分支上尚未发布的最新提交，而不是 PyPI 版本：

pip install git+https://github.com/karmendra8386/agent-cost-mcp-server
agent-cost-mcp-server   # serves over stdio

示例：工具调用的返回内容

针对一次任务尝试调用 compare_models_for_task，使用 10,000 个输入 token 和 2,000 个输出 token，并为几个模型提供示例成功率（请替换为你测得的成功率；未提供成功率的模型会按原始成本排名）：

{
  "input_tokens": 10000,
  "output_tokens": 2000,
  "success_rates": {
    "amazon.nova-micro": 0.2,
    "amazon.nova-lite": 0.6,
    "openai.gpt-5-nano": 0.4,
    "openai.gpt-4o-mini": 0.9,
    "anthropic.claude-haiku-3-5": 0.85,
    "anthropic.claude-sonnet-4-5": 0.95
  }
}

响应内容摘自服务的一次实时运行（定价快照 v1， 2026-10-20；共 18 个排名模型中的前 5 个）：

{
  "input_tokens": 10000,
  "output_tokens": 2000,
  "ranked": [
    {
      "model": "amazon.nova-lite",
      "display_name": "Amazon Nova Lite",
      "cost_per_run_usd": 0.00108,
      "success_rate": 0.6,
      "cost_per_success_usd": 0.0018
    },
    {
      "model": "google.gemini-2.5-flash-lite",
      "display_name": "Gemini 2.5 Flash-Lite",
      "cost_per_run_usd": 0.0018,
      "success_rate": 1.0,
      "cost_per_success_usd": 0.0018
    },
    {
      "model": "openai.gpt-4o-mini",
      "display_name": "GPT-4o mini",
      "cost_per_run_usd": 0.0027,
      "success_rate": 0.9,
      "cost_per_success_usd": 0.003
    },
    {
      "model": "amazon.nova-micro",
      "display_name": "Amazon Nova Micro",
      "cost_per_run_usd": 0.00063,
      "success_rate": 0.2,
      "cost_per_success_usd": 0.00315
    },
    {
      "model": "openai.gpt-5-nano",
      "display_name": "GPT-5 nano",
      "cost_per_run_usd": 0.0013,
      "success_rate": 0.4,
      "cost_per_success_usd": 0.00325
    }
  ],
  "pricing_snapshot": "v1 (2026-10-20)"
}

请注意排名变化：Amazon Nova Micro 的单次运行费用最低 （$0.00063），但由于成功率为 20%，其每项成功任务的排名为第四（$0.00315——平均约需尝试五次才能成功一次）。Nova Lite 的单次运行费用高出 1.7 倍，但每项成功任务的费用最低。

定价快照

价格保存在 src/agent_cost_mcp_server/pricing.json 中，这是主要 Bedrock 和 OpenAI 兼容模型的标价快照（每 100 万 token 的美元价格），日期记录在文件中。价格会变动；做出支出决策前，请对照服务提供商的定价页面进行确认。更新快照只需修改一个文件，服务会在启动时读取该文件。

账本

record_spend 会将记录追加到本地 JSON 账本 ~/.agent-cost-mcp-server/ledger.json。设置 AGENT_COST_LEDGER_PATH 可使用其他文件。任何数据都不会离开本机。

背景

定价和每项成功任务成本模型移植自 tokenecon，这是一个用于按任务核算 Agent 成本的开源库（论文： doi.org/10.5281/zenodo.23195511），其中包含可为 Agent 实时运行计价的 Strands 集成。此服务通过 MCP 提供相同的计算方法，因此任何 Agent 或 IDE 都可以调用。

已通过 RFC #4772 提议将其纳入 awslabs/mcp 集合。

开发

uv sync --extra dev   # or: pip install -e ".[dev]"
pytest

引用

如果你在工作中使用了本软件，请引用软件本身；对于其背后的成本模型和方法，请引用配套预印本。

软件

@software{pandey_agent_cost_mcp_server_2026,
  author = {Pandey, Karmendra},
  title = {agent-cost-mcp-server},
  version = {0.1.1},
  doi = {10.5281/zenodo.23680824},
  url = {https://github.com/karmendra8386/agent-cost-mcp-server},
  date = {2026-10-26}
}

配套预印本

K. Pandey，《Token-Economics for Agentic AI: A Cost Model and Tiered Routing Reference》，Zenodo，DOI 10.5281/zenodo.23195511，2026 年 10 月。

@misc{pandey_tokeneconomics_2026,
  author = {Pandey, Karmendra},
  title = {Token-Economics for Agentic AI: A Cost Model and Tiered Routing Reference},
  doi = {10.5281/zenodo.23195511},
  url = {https://zenodo.org/records/23195511},
  publisher = {Zenodo},
  date = {2026-10}
}

本项目包含 CITATION.cff，供自动化引用工具使用。

许可证

Apache-2.0 — 详见 LICENSE。

版权所有 2026 Karmendra Pandey。