mcpwatch

---

安装 MCP 服务时，没人会告诉你这一点：每次会话开始时，该服务的工具定义都会注入到 Agent 的上下文中，不管你是否使用它。 一个包含 50 个工具的大型供应商集成，可能会在你输入任何内容前就占用 15,000+ 个 Token。下次会话还要再付一次，之后每次也一样。

除此之外，你还要为工具响应付费：你只需要一行数据，它却返回 200 kB；调用失败后重试；以及 Agent 重新获取已有内容。

这些费用无处可见。mcpwatch 会记录传输中的实际字节数，并将其整理成逐项账单。

十秒钟查看你的数字

无需设置，无需重启，无需等待。它会启动你已配置的每个 MCP 服务，像客户端一样向服务请求工具列表，测量用量，然后将其关闭：

npx @sreelal727/mcpwatch audit

Every new session pays ~9,262 tokens ($0.05) to load these tool definitions,
before you type a word:

  github         8,825 tokens   52 tools   95%   Cursor
  filesystem       437 tokens    6 tools    5%   Cursor
                 9,262 tokens  every session

At 10 sessions a day that is ~2,778,600 tokens a month ($13.89 at $5/M) spent
before any work happens.

"github" alone is 95% of that. If you do not use it in every project, moving it to
the projects that need it is the single biggest win available to you.

这是固定成本，无需记录任何内容也能得知。

然后查明你实际使用了什么

你调用的工具中，哪些需要记录真实流量。只需进行一次监测，照常工作一天，然后运行：

npx @sreelal727/mcpwatch init     # then restart your client
npx @sreelal727/mcpwatch cost     # a day later

Your MCP setup costs ~12,486 tokens per session before you type a word ($0.06 at $5/M tokens).

PER-SESSION TAX — tool definitions loaded into every new session:
  github        10,762 tokens   46 tools, none used  ← never called
  filesystem       780 tokens    8 tools, 2 used
  postgres         944 tokens    9 tools, 1 used
                12,486 tokens, every session

AT YOUR ACTUAL PACE — 34.9 server startups/day over 11.3 days:
  ~4,362,755 tokens/month ($21.81) on tool definitions alone, before any work happens
  ~4,939,089 tokens/month ($24.70) all in

BIGGEST SAVINGS — ~1,510,287 tokens ($7.55) of the above bought you nothing:
  1. 1,420,584 tokens (10,762 of them every session) — github: 46 tools loaded into
     every session, never called
     → Remove "github" from your MCP config (or load it only in projects that need it).
  2. 85,523 tokens — filesystem: 132 repeat calls with identical arguments in the same session
     → The agent re-fetched the same thing — usually a sign it lost the earlier result.
  3. 4,180 tokens — postgres: 33 failed calls
     → Fix or remove postgres's failing calls — each one costs context and a retry too.

把前两个数字放在一起看：每月账单中的 $21.81 是工具定义的费用——仅仅是配置了这些服务就要付出的成本，此时你的 Agent 还没做任何有用的事。而其中最大的那个服务，你一次都没调用过。

这就是这个工具的意义所在。它不是“给你一个仪表板，让你自己去找”，而是从配置中删掉这一行，每次会话就能省下 10,762 个 Token；你从未使用过这个服务，却一直在为它付费。

预测使用的是你的记录中观察到的启动频率——不是猜测，而且只有在历史数据足够可靠后才会显示。

（使用 npm i -g @sreelal727/mcpwatch 安装一次，之后每条命令都只需运行 mcpwatch …。）

你的 Agent 也能查看账单

init 还会将 mcpwatch 注册为 MCP 服务，因此你的 Agent 无需额外设置即可使用这些工具：

工具	它能回答的问题
token_costs	“我的 MCP 配置要花多少钱？应该移除什么？”
recent_failures	“刚才出了什么问题？使用了哪些参数？服务端说了什么？”
server_health	“那个服务是否在崩溃、运行缓慢、卡住，或破坏协议？”
find_calls	“这个工具以前成功运行过吗？我上次用了哪些参数？”
get_call	“显示调用 #412 的确切请求和响应 JSON。”

因此，你只需在自己正在使用的客户端中提问：

你： 我的上下文总是被占满，是什么在消耗它？

Agent： （调用 token_costs） 你的 github 服务加载了 46 个工具定义—— 共 10,762 个 token——每个会话都会加载，而且你过去 30 天一次都没调用过它。 按这个时间段计算，大约消耗了 140 万个 token。你的文件系统服务还重复读取了 相同的文件 132 次。要我把 github 从你的配置中移除吗？

这些描述写成了触发条件，因此 Agent 会主动调用它们——工具调用失败后调用 recent_failures，你提到上下文或成本时调用 token_costs——而不是等着你告诉它们这些工具的存在。

它也会告诉你哪里出了问题

同一份记录只需一条命令，就能回答关于可靠性的问题：

$ mcpwatch doctor
2 error(s) in 19 MCP calls across 3 server(s) in the last 24h.

! web-fetch        5 calls, no errors, avg 152ms   last seen 32s ago
    1 non-protocol stdout line (this server logs to stdout, which corrupts MCP)
✗ database         7 calls, 2 errors (29%), avg 227ms   last seen 34s ago
    high error rate
    slowest: run_query at 1.3s
✓ filesystem       7 calls, no errors, avg 54ms   last seen 36s ago

[#14] 2s ago  database/does_not_exist  tool_error  (2ms)
    error: MCP error -32602: Tool does_not_exist not found
    session fd14d19f · full payloads: get_call(14)

mcpwatch tail 会实时逐行输出调用记录。所有命令都支持 --json，因此只有 Shell 访问权限的 Agent（例如在 VS Code 终端中运行的 Codex、钩子、CI）也能读取。你也可以运行 mcpwatch ui，在 127.0.0.1 上打开本地仪表板，亲自查看。

你将获得

• 十秒内得到一个数字——mcpwatch audit 无需插桩、无需重启客户端，也无需等待流量，即可为已配置的服务估算成本。
• 逐项列出的 token 账单——mcpwatch cost 会计算每个服务每个会话的开销，根据你的实际使用情况预测未来成本，并按可移除项排序：未使用的服务、臃肿的工具列表、过大的响应、重复调用、失败调用。
• Agent 可读的记录——将 token_costs、recent_failures、server_health、find_calls、get_call 作为 MCP 工具提供，并且所有命令都支持 --json，方便只有 Shell 访问权限的 Agent 使用。你的 Agent 不再需要猜测自己的工具调用情况。
• 实时仪表板——Agent 工作时，会话记录会实时流入：调用时间线、状态指示点、延迟条形图、完整的请求／响应 JSON 检视、筛选，以及深色／浅色模式。
• 记录每次调用——保存成对的请求／响应，以及耗时和状态（ok / rpc_error / tool_error），包括客户端经常悄悄吞掉的带内工具错误。
• 检测行为异常的服务端——将日志写入 stdout 的服务端会破坏 MCP 协议；mcpwatch 会记录这些行并将其标记出来，而不是因此导致协议中断。
• 默认启用密钥脱敏——API 密钥、Bearer token、JWT 和类似密码的 JSON 字段都会从存储副本中清除（不会处理实时数据流）。使用 --no-redact 可关闭，使用 MCPWATCH_REDACT_EXTRA 可添加匹配模式。
• 导出会话——mcpwatch export <id> 会生成一个独立的 HTML 文件，作为可分享、无脚本的故障报告，准确呈现发生过的事情。
• 也支持 HTTP 服务——mcpwatch http <url> 是一个用于 Streamable HTTP 服务的记录型反向代理（也包含 SSE 响应）。
• 数据归你，存储在你的磁盘上——使用 mcpwatch gc 管理保留期限；删除 ~/.mcpwatch，数据就会消失。永远没有 SaaS、账户或遥测。

工作原理

your agent ──stdio──▶ mcpwatch run ──stdio──▶ your MCP server
    ▲                      │
    │                      └── tee ──▶  SQLite (~/.mcpwatch)
    │                                        │
    └──── mcpwatch mcp ◀─────────────────────┤   the agent reads its own history
                                             │
          mcpwatch ui / doctor / tail ◀──────┘   you read it, when you want to

mcpwatch init 会重写客户端配置中的每个 stdio 服务条目，使其通过 mcpwatch run 路由。代理会原样传递字节流，并解析该数据流的一个副本——捕获功能与透传功能独立接线，因此即使录制失败，Agent 仍能继续工作。透传至关重要是设计原则 #1，已在代码中落实，并通过端到端测试验证：测试会让真实 MCP 客户端通过代理运行。

init 还会将 mcpwatch 本身添加到客户端，作为一个 MCP 服务，从而形成闭环：录制器也成为 Agent 可以调用的工具。它绝不会通过自己的代理进行包装——否则，Agent 针对流量提出的每个问题都会变成更多流量。

对比

	mcpwatch	MCP Inspector	mcpsnoop	SaaS Agent 可观测性
告诉你当前配置的服务会消耗多少令牌	✅ cost	❌	❌	部分支持（可查看支出，但无法查看每个服务的开销）
你的 Agent 可以查询录制内容	✅ MCP 工具	❌	❌	❌
来自你实际客户端的真实会话	✅	❌ 手动开发工具	✅	✅
无头／仅终端工作流	✅ doctor、tail	❌	✅	❌
Web 仪表板	✅	✅	❌ 终端 TUI	✅
一条命令配置整个客户端	✅ init	❌	❌ 每个服务单独配置	❌ 需要更改 SDK／Agent
实时跟踪	✅	❌	✅	✅
自包含的 HTML 会话导出	✅	❌	❌	❌
100% 本地运行，无需账户	✅	✅	✅	❌
策略防护措施	🔜 v1.0	❌	❌	因平台而异

（这些工具都很不错——这里比较的是它们各自适用的场景。Inspector 非常适合调试你正在开发的服务；mcpsnoop 是一款可靠的终端查看器；SaaS 平台则会在其基础设施上提供集群管理功能。）

命令

命令	功能
mcpwatch audit [--json]	立即衡量已配置服务的每会话开销——无需设置
mcpwatch init [--dry-run]	为客户端添加监控，并向 Agent 提供 mcpwatch 工具（会创建备份，且可还原）
mcpwatch cost [--since 30d] [--rate N] [--json]	详细的令牌账单：每会话开销、月度预估、按节省金额排序
mcpwatch doctor [--json]	一次性健康报告：列出出错、崩溃、挂起、运行缓慢或破坏协议的服务
mcpwatch tail [--json]	在终端实时跟踪调用，每次调用显示一行
mcpwatch mcp	将 mcpwatch 作为 MCP 服务运行（由客户端启动；通常你无需手动运行）
mcpwatch connect	输出可复制粘贴的 Claude Code / Codex / Cursor 配置
mcpwatch unwrap	还原原始配置
mcpwatch status	显示已添加监控的内容
mcpwatch ui [--port 4680]	本地仪表板
mcpwatch run --name X -- <cmd>	手动包装单个 stdio 服务
mcpwatch http <url> [--port 4681]	为 Streamable HTTP 服务提供录制反向代理
mcpwatch sessions / calls <id>	通过命令行查看录制数据
mcpwatch export <id> [--out f.html]	导出自包含的 HTML 会话
mcpwatch gc [--keep-days 30]	清理旧会话，压缩数据库

常见问题

Token 数量有多准确？ 这些数字根据记录的字节数估算得出，大约按每个 Token 对应 4 个字符计算，并未使用真正的分词器——要在这里集成一个分词器，就得在用户全局安装的 CLI 中加入原生依赖。这个精度足以判断哪些操作开销大，以及比较不同服务，这才是你真正需要用到的。不要拿它们来核对账单。金额按你可以通过 --rate 设置的费率计算（默认每百万 Token 5 美元），并且总会打印出采用的费率。

这能降低我的托管或数据库账单吗？ 不能直接降低——mcpwatch 是本地记录器，不是基础设施。不过，它会显示哪些重复工作正在给你的后端增加负担：重复的相同调用、过大的查询、重试循环。解决这些问题可以减少 API 配额消耗和数据库负载。但坦白说，最主要的收益在于上下文 Token，而节省也确实体现在这里。

记录本身会消耗 Token 吗？ 不会。捕获过程是在你的机器上进行的字节级分流；不会向任何提示词中添加内容。只有当 Agent 实际调用 Agent 工具时，它们才会进入上下文，而且其回答会经过限制和摘要，不会直接倾倒全部内容。

有开销吗？ 代理会进行字节级分流；解析和存储则基于副本进行，不会影响协议的关键路径。如果捕获过程发生故障（磁盘已满等），它会自行禁用，流量仍会继续传输。

我的数据安全吗？ 数据绝不会离开你的机器：数据存储在 ~/.mcpwatch 中的 SQLite 数据库里，仪表板绑定到 127.0.0.1，并且默认在写入时对密钥进行脱敏。Agent 工具读取的是同一个已脱敏的本地数据库——将记录交给 Agent 不会把数据发送到原本不会发送的地方。

我的客户端没有被自动检测到。 运行 mcpwatch connect，即可获取可复制粘贴的配置片段，适用于 Claude Code（claude mcp add）、Codex（~/.codex/config.toml）、Cursor 或其他 MCP 客户端。Agent 工具并非 Claude 专属——它就是一个普通的 MCP 服务。

Agent 每次都会读取我的全部历史记录吗？ 不会。工具会返回经过限制和摘要的结果（十几行数据，以及参数预览），并默认使用最近的时间范围。只有当 Agent 针对某次特定调用提出请求时，才会返回完整负载。

护栏呢？ 这是 v1.0 的计划：针对每个服务／工具设置允许／拒绝规则，为危险调用提供确认提示，并对工具描述变更发出警报（“抽地毯”攻击）。你现在使用的记录器正是这些功能的基础。请参阅 ROADMAP.md。

开发

npm install && npm run build && npm test

单体仓库：packages/cli（代理 + CLI + 仪表板服务）， packages/ui（React 仪表板，构建后会放入 CLI 包）。 用于开发 UI 的演示数据：

cd packages/cli
npx tsx scripts/seed-demo.ts /tmp/mcpwatch-demo.db --keep-running &
node dist/index.js ui --db /tmp/mcpwatch-demo.db

欢迎贡献——请查看路线图，了解项目的发展方向。

许可证

MIT