claude-code-usage

Claude Code の使用状況

Claude Code のトークン使用量、推定コスト、プラン上限の状況を、任意の MCP クライアント（Zed、Claude Desktop、Cursor など）に表示する MCP サーバーです。Claude Code 自身のログ（~/.claude/projects/**/*.jsonl）と Anthropic の使用状況 API を読み取り、エージェントが呼び出せるツールとしてデータを公開します。

npm では claude-code-usage-mcp として、また公式 MCP レジストリでは io.github.wheelbarrel00/claude-code-usage として公開されています。

利用できる機能

2 つのツールがあります。

• get_claude_usage — 今日のコストとトークン数、5 時間および週間のプラン上限使用率（リセット時刻とペース予測付き）、最近の消費速度、現在のコンテキストウィンドウ使用率、および従量課金の追加使用量を確認できます。
• get_usage_breakdown — モデル、プロジェクト、セッション、Git ブランチ別、または期間別（月ごとの日次／全期間の月次）に使用状況を分類できます。

エージェントには、「今の 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）は、"context_servers" の代わりに "mcpServers" の下で同じコマンドを使用します。

必要条件

認証済みの Claude Code がインストールされている必要があります。このサーバーは、CLI が書き込むものと同じファイルである ~/.claude/.credentials.json と ~/.claude/projects を読み取ります。

設定

以下の環境変数は任意です。

変数	デフォルト	説明
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 の設定ディレクトリを上書きします。

動作の仕組み

プランの最新の上限は、ディスク上にすでに保存されている OAuth トークンを使用して api.anthropic.com/api/oauth/usage から取得します。アクセストークンはメモリ内でのみ更新されるため、実行中の 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 で Extensions → Install Dev Extension を開き、このリポジトリのルートフォルダーを選択します。

ライセンス

MIT