token-meter

Token Meter

在本地跟踪 Claude Code、Codex 和 Cursor 的令牌用量及费用——无需账户，也不使用云服务。

一个本地仪表板，集中查看 Claude Code 和 Codex 的令牌用量。 免费，支持 MCP，核心采用 MIT 许可证。

npm：@whdrnr2583/token-meter · GitHub：whdrnr2583-cmd/token-meter · 网站：token-meter.dev

Token Meter 会解析 Claude Code 和 Codex 已写入磁盘的 JSONL 文件， 并将其转换为实时仪表板：按项目、模型、MCP 工具和小时统计费用。你的数据绝不会离开你的设备。

运行首次审计

npx -y @whdrnr2583/token-meter audit

扫描已导入的 Claude Code 和 Codex 历史记录，找出费用高昂的会话、 响应过大的工具、运行缓慢的工具、重复调用和缓存浪费，并按费用和置信度排序。审计完全基于本地 SQLite 数据库运行—— 与 Token Meter 的其他功能一样，数据仅在本地处理，不使用云服务。添加 --json 可输出机器可读的结果；完整的标志列表和 JSON 架构请参阅 docs/audit.md。

适用场景

如果你符合以下情况，可以使用 Token Meter：

• 想知道 Claude Code 或 Codex 会话消耗了多少令牌和费用，并按项目、模型和 MCP 工具细分
• 使用固定费用套餐（Claude Max 等），想了解等效的 API 费用
• 想找出哪个 MCP 服务或工具消耗的令牌最多，或一天中哪个时段费用最高
• 想恢复最近的会话，并需要随手可用的 claude --resume / codex resume 命令
• 想离线完成以上所有操作，无需账户，也不会上传任何内容

如果你需要与 Anthropic 或 OpenAI 账单核实、可用于计费的精确数据，则不适合使用本工具——Token Meter 仅根据本地 JSONL 文件计算预估值。

MCP 工具

将 Token Meter 配置为 MCP 服务（install-mcp all）后，你的 AI 助手即可使用以下四个工具：

工具	返回内容
usage_summary	按日和模型细分的令牌数量、等值美元费用及调用次数每日汇总表
recent_sessions	最近的会话，以及可直接粘贴使用的 claude --resume / codex resume 命令
session_tools	会话内按工具细分的数据：调用次数、令牌总数、平均延迟和响应大小
refresh_data	重新扫描本地 JSONL 日志中的新活动，然后返回最新汇总

这四个工具均为只读。数据绝不会离开你的设备。

提示词示例

安装 MCP 服务后，可将以下任意提示词复制粘贴到 Claude Code 或 Cursor 中：

Show me my token usage and cost for the last 7 days.

List my recent sessions so I can pick one to resume.

Show the tool breakdown for my most recent session — which tool used the most tokens?

Refresh token-meter data, then tell me which model cost the most this week.

Which hour of the day am I spending the most tokens on?

快速开始

npx @whdrnr2583/token-meter ingest        # scan ~/.claude/projects + ~/.codex/sessions
npx @whdrnr2583/token-meter stats 30      # CLI summary for last 30 days
npx @whdrnr2583/token-meter serve         # http://localhost:8765 dashboard
npx @whdrnr2583/token-meter mcp           # run as an MCP server for Claude Code / Cursor

该软件包使用 npm 作用域（@whdrnr2583/）发布，因为 npm 上的纯名称 token-meter 与一个现有的相似名称冲突。安装后，CLI 二进制文件仍名为 token-meter。

将 Token Meter 连接到你的 AI 工具（MCP）

运行一条命令，即可将 Token Meter 注册到你计算机上所有受支持的客户端：

npx -y @whdrnr2583/token-meter install-mcp all

支持 Claude Code、Cursor 和 Claude Desktop，操作可重复执行，会备份现有配置，并保留其他 MCP 服务。单客户端版本： install-mcp claude-code | cursor | claude-desktop。添加 --dry-run 可预览。

或者让你的大模型来操作。 打开 Claude Code / Cursor / Claude Desktop，然后询问： “阅读 https://raw.githubusercontent.com/whdrnr2583-cmd/token-meter/main/docs/mcp-server.md 并将 token-meter 设置为我的 MCP 服务。”

手动一行命令（如果你不想运行我们的安装程序）：

客户端	命令 / 配置
Claude Code	claude mcp add token-meter -- npx -y @whdrnr2583/token-meter mcp，然后运行 claude mcp list 进行验证
Cursor	编辑 ~/.cursor/mcp.json（Windows：%USERPROFILE%\.cursor\mcp.json）——参阅 docs/mcp-server.md
Claude Desktop	编辑 claude_desktop_config.json——参阅 docs/mcp-server.md
ChatGPT	目前仅支持 Stdio；HTTP 封装方案见 docs/mcp-server.md
其他（Continue、Zed、自定义）	通过 Stdio 运行 npx -y @whdrnr2583/token-meter mcp

然后询问：“用 token-meter 显示我最近的会话”，或“用 token-meter usage_summary 显示本周的用量”。

Claude Code 快捷方式： 运行一次 npx -y @whdrnr2583/token-meter install-command claude-code，即可注册 /token-meter 斜杠命令。重新打开会话后，输入 /token-meter，即可一次性查看摘要，无需使用自然语言。

完整的设置、验证和故障排除说明：docs/mcp-server.md。

存储位置：~/.tokenpulse/usage.db（SQLite）。删除此文件夹即可重新开始。 未来版本会将文件夹名称改为 ~/.tokenmeter/，并自动迁移；在此之前，v0.1 目录会保留原名称。

你会看到什么

• 美元等值成本：按天、模型和项目统计。如果你使用 Max 计划，想了解 API 调用原本会产生多少费用，这项数据会很有用。
• MCP 和工具明细：哪个 MCP 服务消耗的令牌最多、每种工具的平均耗时，以及每次调用的响应大小。
• 输出令牌的每小时分布。
• Claude Code 和 Codex 并排显示，一览无余。

关于美元金额的说明

费用是根据 Claude Code 和 Codex 已写入 JSONL 文件的令牌数量，在本地计算的估算值，并乘以模型公布的每百万令牌费率。这些金额未经你的 Anthropic / OpenAI 实际账单验证，并且可能因以下原因而产生偏差：

• 供应商会调整价格；src/pricing.ts 中的表格只是某一时点的快照
• 订阅计划（Pro / Max）按固定费用计费——屏幕上显示的美元金额是 API 调用原本会产生的费用，而不是你实际支付的金额
• 某些令牌类别（服务端工具调用、缓存写入类型）采用了近似计算

请将这些数据视为用于发现浪费的相对参考信号，而非账单级别的核算结果。Token Meter 提供了一个回归测试，用于验证计算可复现；还提供了一个审计脚本，用于检查不变量；但这两者都不会根据供应商账单验证费率。

为什么采用本地优先

• 你的 JSONL 文件包含源代码、提示词和工具结果。Token Meter 不会上传其中任何内容。它只使用启发式方法、正则表达式和 SQL 聚合。
• 无需集成 SDK；免费版也无需配置代理。
• CLI 和仪表板核心部分采用 MIT 许可证。

定价

层级	价格	可获得内容
免费版	$0	Claude Code + Codex 解析、MCP/工具明细、按小时/模型/项目细分、7 天历史记录、1 条桌面提醒
Pro	$5/mo	包含免费版的所有内容，并以月度支出回顾的形式呈现：30 天历史记录（本月与上月对比）、按会话/消息深入查看，定位导致预算超支的运行记录、缓存效率节省的金额、浪费信号（工具响应过大 + 缓存未能发挥作用），以及不限数量的智能提醒（桌面 + webhook）
Pro+	later	本地 LLM 代理（Ollama / LM Studio / llama.cpp / vLLM）、GPU/VRAM 跟踪、自动操作

Pro 的不同之处在于：它让你从瞥一眼上周的数字，转变为审视本月支出流失在了哪里。Pro 已上线 — 在 token-meter.dev 订阅。

Pro+ 将在 Pro 注册人数和社区需求确认这一细分市场后推出。

路线图

• M1 ✅ Claude Code 解析、MCP/工具明细、按小时统计
• M2 ✅ 集成 Codex
• M3 ✅ Pro 层级（$5）、Polar.sh 计费、许可证激活
• M4+ Pro+（本地 LLM 代理、GPU 跟踪），是否推出视需求而定

隐私与安全

• Token 数量根据 Claude Code 和 Codex 已生成的 JSONL 文件进行统计。 Token Meter 不会调用任一供应商的网络 API。
• 默认不存储提示词或响应正文 — 仅存储元数据 （时间戳、Token 数量、工具名称、响应长度）。
• 数据库位于 ~/.tokenpulse/ 下；删除该目录即可清除数据。（未来版本将重命名为 ~/.tokenmeter/，并自动迁移。）

更新日志

有关发行说明和重大变更，请参阅 CHANGELOG.md。

许可证

CLI、仪表板和解析器采用 MIT 许可证。Pro 层级功能将在独立的软件包中提供，并采用闭源许可证。