mcp-usage

mcp-usage

ローカルの Claude Code のトランスクリプトを読み取り、接続している各 MCP サーバーについて、実際に使用されているのか、すべてのセッションでアイドル状態なのか、接続に失敗しているのか、何週間も認証を待っているのか、そしてどのサーバーを切断すべきなのかを知らせる、小規模で目的を絞った MCP サーバーおよび CLI です。

ひとつの目的のために作られています。「どの MCP サーバーを残すべきか？」という問いに、ローカルで、読み取り専用で、会話の内容を一切外部に漏らすことなく答えます。

ツール

すべて読み取り専用の 4 つのツールです。

ツール	内容
usage_summary	サーバーごとに 1 行で、ステータス、公開されているツール、セッション数、呼び出し数、エラー率、推定結果トークン数、最終使用日時を表示します
unused_servers	接続されていたものの一度も呼び出されなかったサーバー、接続に失敗したサーバー、認証待ちのサーバーを表示します
server_details	1 つのサーバーについて、ツールごとの呼び出し数、エラー数、結果サイズを含む詳細を表示します（ID またはラベルを大文字・小文字を区別せずに指定できます）
recommendations	優先順位付きの対応リストを表示します。切断、修正または削除、認証または削除、エラーの調査、大きな結果の確認

設計上の選択：

• 推測ではなく、正確な情報です。 Claude Code は各セッションで、どの MCP ツールが利用可能だったか、どのサーバーが失敗したか、または認証が必要だったかをすでに記録しています。「利用可能だったが一度も使われなかった」は、独自ログの集合差分であり、ヒューリスティックではありません。
• 設計上、プライバシーが守られます。 ネットワーク関連のコードは一切ありません。出力に含まれるのはサーバー名、ツール名、件数、バイト数、タイムスタンプのみで、プロンプト、応答、ツール入力、ツール出力、ファイルパス、エラーメッセージは含まれません。テスト用フィクスチャでは、実際のトランスクリプト内のプライベートな内容すべてに SECRET_* マーカーを埋め込んでおり、それらがライブラリ、CLI、MCP 出力のいずれにも渡らないことをテストで検証しています。
• 大きな履歴も高速に処理します。 トランスクリプトは 1 行ずつストリーミングされ、関係のない行は JSON.parse の前にスキップされます。約 360 MB の履歴（90 MB のセッションを含む）を約 3 秒でスキャンします。
• 使用状況の整理が目的で、料金の計算ではありません。 コスト分析ツール（ccusage、agent-cost-mcp、…）は、使用したトークン数や金額を教えてくれます。このツールは、どのサーバーを使い続ける価値があるかを教えてくれます。
• すべてのツールには、厳格な入力スキーマと MCP アノテーション（readOnlyHint、idempotentHint）が付属しており、ホスト側で自動承認できます。

要件

• Node.js 22 以降。
• Claude Code（CLI、デスクトップアプリ、または 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 を見つけられない場合（シェルの 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	対象期間中に少なくとも 1 回呼び出されました
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