claude-code-usage

Claude Code 使用情况

一个 MCP 服务，可在任意 MCP 客户端（Zed、Claude Desktop、Cursor 等）中显示 Claude Code 的令牌用量、预估费用和计划限额状态。它会读取 Claude Code 自身的日志（~/.claude/projects/**/*.jsonl）以及 Anthropic 的用量 API，然后将数据作为 Agent 可调用的工具提供。

已发布到 npm，名称为 claude-code-usage-mcp，并收录于官方 MCP 注册表，名称为 io.github.wheelbarrel00/claude-code-usage。

可获取的数据

两个工具：

• get_claude_usage — 今日费用和令牌用量、5 小时和每周计划限额使用情况（含重置时间和进度预测）、近期消耗速率、当前上下文窗口填充情况，以及按量付费的额外用量。
• get_usage_breakdown — 按模型、项目、会话或 Git 分支分组的用量，或按时间分组（本月按日／历史按月）。

可以向 Agent 提问，例如 “我现在的 Claude 用量是多少？” 或 “按项目细分我本月的 Claude 支出。” MCP 工具会按需查询，不会持续显示在状态栏中。

安装

npx -y claude-code-usage-mcp

在客户端中注册。对于 Zed（settings.json）：

{
  "context_servers": {
    "claude-code-usage": {
      "command": "npx",
      "args": ["-y", "claude-code-usage-mcp"]
    }
  }
}

对于 Claude Desktop（claude_desktop_config.json），在 "mcpServers" 下使用相同的命令，而不是 "context_servers"。

要求

需要已通过身份验证的 Claude Code 安装 — 服务会读取 ~/.claude/.credentials.json 和 ~/.claude/projects，这些文件由 CLI 写入。

配置

可选环境变量：

变量	默认值	含义
CCU_CURRENCY	USD	用于费用格式化的 ISO 货币代码。
CCU_DECIMALS	2	费用数值的小数位数。
CCU_USE_LIVE_API	true	从 Anthropic 获取实时限额；失败时回退到磁盘缓存。
CCU_LIVE_MIN_INTERVAL_SECONDS	180	两次实时用量请求之间的最短间隔秒数。
CCU_BURN_WINDOW_MINUTES	15	计算消耗速率时使用的回溯时间窗口。
CCU_PROJECT_GROUPING	git	项目细分所用的分组方式：git、folder 或 flat。
CLAUDE_CONFIG_DIR	~/.claude	覆盖 Claude Code 配置目录。

工作原理

实时计划限额通过 api.anthropic.com/api/oauth/usage 获取，使用的是磁盘上已有的 OAuth 令牌；访问令牌只会在内存中刷新，因此不会将正在运行的 Claude Code 会话登出。令牌和费用数据则从本地会话日志中解析。

仓库结构

• mcp-server/ — MCP 服务（TypeScript，打包到 dist/server.mjs）。
• extension.toml、Cargo.toml、src/lib.rs — 独立的 Zed 扩展，内嵌并启动该服务（可替代上述 npx 安装方式）。

从源代码构建

cd mcp-server
npm install
npm run build      # bundles to dist/server.mjs
node dist/server.mjs --selftest

Zed 扩展（独立运行，无需 npm）

Zed 扩展会内嵌打包后的服务，并使用 Zed 自带的 Node 启动。先构建服务，安装 rustup 和 WebAssembly 目标（rustup target add wasm32-wasip1），然后在 Zed 中打开 扩展 → 安装开发扩展，并选择此仓库的根目录。

许可证

MIT