mcp-usage

mcp-usage

一款小巧、专注的 MCP 服务和命令行工具，可读取你的本地 Claude Code 对话记录，并告诉你所连接的每个 MCP 服务是实际使用中、在每个会话中都处于闲置状态、连接失败，还是已经等待授权数周，以及哪些服务可以断开连接。

专为一项任务打造：回答*“我应该保留哪些 MCP 服务？”*——在本地以只读方式完成，绝不泄露对话中的任何内容。

工具

四个工具，全部只读：

工具	功能
usage_summary	每个服务占一行：状态、公开的工具、会话数、调用次数、错误率、估算的结果令牌数、最近使用时间
unused_servers	已连接但从未调用的服务、连接失败的服务，或等待授权的服务
server_details	完整显示单个服务的详情，包含各工具的调用次数、错误和结果大小（接受 ID 或标签，不区分大小写）
recommendations	按优先级排列的操作列表：断开连接、修复或移除、授权或移除、调查错误、处理过大的结果

设计选择：

• 精确，而非猜测。 Claude Code 已在每个会话中记录哪些 MCP 工具可用、哪些服务连接失败或需要授权。“可用但从未使用”是对你自己的日志进行集合差运算得出的结果，并非启发式判断。
• 从设计上保护隐私。 完全不包含网络代码。输出只包含服务名称、工具名称、计数、字节总数和时间戳——绝不包含提示词、响应、工具输入、工具输出、文件路径或错误消息。测试固件会在真实对话记录中所有存放私密内容的位置植入 SECRET_* 标记，并通过测试断言这些标记不会进入库、命令行工具或 MCP 输出。
• 处理大型历史记录也很快。 对话记录按行流式读取，并在 JSON.parse 之前跳过无关行：扫描约 360 MB 的历史记录（包括一个 90 MB 的会话）只需约 3 秒。
• 关注使用情况，而非计费。 费用分析工具（ccusage、agent-cost-mcp，……）会告诉你用了多少令牌、花了多少钱；本工具会告诉你哪些服务值得保留。
• 每个工具都提供严格的输入架构和 MCP 注解（readOnlyHint、idempotentHint），方便宿主自动批准。

要求

• Node.js 22 或更高版本。
• Claude Code（命令行工具、桌面应用或 IDE 扩展），且本机上有一些会话历史记录。无需其他任何东西：不需要账户、API 密钥或配置。

1. 运行报告

无需安装，npx 会从 npm 获取软件包（@rixtay/mcp-usage，安装的命令为 mcp-usage）：

npx -y @rixtay/mcp-usage

或从克隆的仓库运行：

git clone https://github.com/Rixtayz/mcp-usage.git
cd mcp-usage
npm install && npm run build
node dist/bin/cli.js

选项	用途
--since <days>	回溯指定天数（默认 30）
--project <path>	仅扫描路径中包含此文本的项目
--min-sessions <n>	将闲置服务标记出来前所需的会话数（默认 5）
--dir <path>	Claude 配置目录（默认：$CLAUDE_CONFIG_DIR 或 ~/.claude）
--json	以 JSON 格式输出完整报告，包括各工具的统计数据

文本输出会截断较长的列表；--json 始终包含全部内容。

2. 连接到 Claude Code

claude mcp add --scope user --transport stdio mcp-usage -- npx -y @rixtay/mcp-usage serve

3. 连接到 Claude Desktop / Cowork / 任意 MCP 客户端

mcp-usage 已在官方 MCP Registry 中登记为 io.github.Rixtayz/mcp-usage，因此可以通过浏览该注册表的客户端按名称安装。否则，请手动配置：

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（或在 Windows 上编辑 %APPDATA%\Claude\claude_desktop_config.json），也可以通过 设置 → 开发者 → 编辑配置 打开该文件。

{
  "mcpServers": {
    "mcp-usage": {
      "command": "npx",
      "args": ["-y", "@rixtay/mcp-usage", "serve"]
    }
  }
}

如果宿主找不到 npx（它可能没有继承你的 shell PATH），请改用绝对路径："command": "/absolute/path/to/node"，"args": ["/absolute/path/to/mcp-usage/dist/bin/cli.js", "serve"]。

无论在哪个位置运行，服务都会读取 Claude Code 的对话记录，因此它只适用于你使用 Claude Code 的机器上的本地会话。

4. 示例提示词

• “我应该断开哪些 MCP 服务？”
• “哪些服务等待授权的时间最长？”
• “Playwright 好像不太稳定。它的哪些工具最常失败？”
• “过去 7 天里，我是否使用过 Context7 以外的任何东西？”

典型流程：recommendations → 助手提出清理列表，你确认 → 对有疑问的项目使用 server_details → 自行断开服务。工具绝不会触碰你的 MCP 配置。

报告内容

每个服务会有一个状态：

状态	含义
used	在统计时间段内至少调用过一次
unused	其工具可用，但从未被调用
failed	从未提供工具；Claude Code 报告了连接失败
needs-auth	从未提供工具；正在等待授权

建议按优先级排序：

操作	规则
disconnect	未使用，且在至少 5 个会话中可用（--min-sessions）
fix-or-remove	至少在 3 个会话中连接失败
authorize-or-remove	至少在 3 个会话中等待授权
investigate-errors	至少调用 5 次，且其中至少 30 % 失败
heavy-results	结果平均每次调用的估算令牌数至少为 10,000

开发

npm test          # vitest: name parsing, streaming parser, aggregation, rules, CLI, MCP tools over an in-memory transport
npm run typecheck
npm run inspect   # MCP Inspector against the built server

目录结构：

src/bin/cli.ts             entry point: `mcp-usage` prints the report, `mcp-usage serve` serves stdio
src/cli.ts                 argument parsing and output
src/server.ts              builds the McpServer and registers the four tools
src/analyze.ts             options → report; the one function both shells call
src/parser.ts              streaming JSONL reader → typed events
src/aggregate.ts           events → per-server stats
src/recommend.ts           stats → prioritized recommendations
src/report.ts              text table rendering
src/scan.ts                transcript discovery (--since, --project)
src/adapters/claude-code.ts  the only client-specific code, behind a small ClientAdapter interface
src/names.ts               `mcp__<server>__<tool>` parsing and server id mangling

技术栈：@modelcontextprotocol/sdk v1、zod v4，运行时不依赖其他内容。设计说明：docs/DESIGN.md。

值得了解的事项

• 对话记录格式并非公开 API。 解析时采用防御性处理——所有字段均可选，忽略未知记录，统计并跳过格式错误的行——但未来的 Claude Code 版本仍可能导致解析失效。已针对 Claude Code 2.1.233 – 2.1.274 进行测试。
• 令牌数是估算值：结果字节数 ÷ 4，仅统计文本。对话记录不包含每个结果的令牌数，图片结果也不计入。
• 工具名称会在 mcp__ 前缀之后的第一个 __ 处分割。 服务 ID 可以包含下划线、连字符、点号，也可以是纯 UUID；工具名称本身也可能包含 __，因此直接使用 split("__") 会导致统计错误。
• 同一个连接器可能会以两个名称出现——在 CLI 中显示为易读名称，在桌面应用中则显示为 UUID。它们不会合并。
• Claude 桌面应用捆绑的服务（ccd_*）会显示在报告中，但绝不会被标记为建议断开：你无法移除它们。
• Claude Code 会删除旧对话记录，因此较长的 --since 时间范围只会涵盖仍保留在磁盘上的记录。
• 目前仅支持 Claude Code。欢迎为其他客户端开发适配器。

贡献

欢迎提交错误报告、修复和其他 MCP 客户端的适配器：请参阅 CONTRIBUTING.md。如果 Claude Code 更新后报告突然变得不准确，请附上 Claude Code 版本并提交错误报告。如果发现该工具可能泄露对话记录内容，请按照 SECURITY.md 中的说明私下报告。

发布历史：CHANGELOG.md。

许可证

MIT