@vk0/agent Cost Mcp

agent-cost-mcp

Claude Code の AI エージェント向けローカルコストガードと実行時ガードレール。

現在の v2.3.3 リリースもローカルファーストの方針を維持し、オペレーター向けの単一タスクに焦点を当てています。支出の発生源と今後の見通しを表示し、プロバイダー／モデル／ツールごとにコストを割り当て、subtreeCost でサブエージェントツリーを集計し、ホスト型のコントロールプレーンを導入することなく、署名付きモニター Webhook アラートを送信できます。

Claude Code 向けコストガード。 @vk0/agent-cost-mcp はローカルの JSONL セッションログを読み取り、/cost の後に知りたくなる疑問に答えます。実際にトークンを消費しているのはどのツール、ブランチ、リトライループ、あるいは暴走パターンなのか、次に何を変更すべきなのか。2.3.3 では、集計された日次トレンドと異常値のベースラインがアシスタント行のタイムスタンプに基づくため、古い複数日分の JSONL ファイル内にある直近の日のデータが表示されなくなることはありません。クラウドは不要です。API キーも不要です。

言語： 英語 · 日本語 · 简体中文 · Русский · Español

なぜ／いつ使うか

Claude Code がコストの数値は表示してくれたものの、その理由まではわからないときに使います。

すばやく状況を把握するには、標準の /cost、ccusage、または cctally を使います — 合計、ステータスライン、日次使用量、サブスクリプション枠のダッシュボードなどです。次に知りたいのが「どのツール、サブエージェント、またはブランチが予算を消費したのか」「実行を続けたらどうなるのか」「エージェントは次に何をすべきか」であり、それを JSONL からローカルで機械可読な形式で確認したい場合は、@vk0/agent-cost-mcp をお使いください。

コストガードが役立つ代表的なケース：

• ツールを多用するセッション： 1 回または複数回の実行において、コストの割合、コンテキストの割合、ROI の低い呼び出しパターンを支配しているツールを特定します。
• リトライループと暴走動作： 繰り返されるターン、放棄されたツール呼び出し、異常値が発生した日、ブランチ単位の消費パターンを、気付かないうちに累積する前に検出します。2.3.3 では、日次トレンドと異常値のベースラインがアシスタント行のタイムスタンプに基づくため、古い複数日分の JSONL ファイル内にある直近のアクティビティが、オペレーターの画面から消える可能性が低くなります。
• 事前の支出ガードレール： 想定される実行コストを見積もり、予算のしきい値を設定し、次の長時間のエージェント実行が許容範囲を超える前にモニターアラートを送信します。

Claude Code セッション向けに、ローカルでプライバシーを保護し、設定不要でコストを調査できる機能とガードレールを求めるユーザーには、これが標準的な選択肢です。すべての処理は、既存のセッションログ ~/.claude/projects/ を使ってユーザーのマシン上で実行されます。

Claude Code のセッションログの保存場所： ~/.claude/projects/<project>/ の下にあるセッションごとの .jsonl ファイルを確認してください。たとえば、~/.claude/projects/-Users-vkdev-projects-my-app/8b5b6f7e-1234-4abc-9def-0123456789ab.jsonl です。クライアントがすでに正確なファイルを把握している場合は、その具体的なセッションパスを渡してください。そうでない場合は、Agent Cost MCP に ~/.claude/projects/ 配下の該当するプロジェクトフォルダーを指定し、そこにある最近の JSONL ファイルを調べてください。

対象外

これは、請求ダッシュボード、調達コンソール、組織の財務システム、請求書の信頼できる情報源ではありません。

ローカルの Claude Code ログから Cost Guard のような回答を得たい開発者やオペレーター向けであり、費用の振り分けレポート、全社的な支出会計、実行時のライブイントロスペクション向けではありません。

インストール

クライアントを選択してください。どの方法でも npx を使うため、グローバルにインストールする必要はありません。

Claude Desktop

Claude Desktop の設定ファイルを編集します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

mcpServers の下に agent-cost エントリを追加します。

{
  "mcpServers": {
    "agent-cost": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-cost-mcp"]
    }
  }
}

Claude Desktop を終了して再起動します。チャット入力欄の右下にある MCP インジケーターに、新しいツールが4つ表示されるはずです。

Claude Code

CLI からワンライナーを実行します。

claude mcp add --transport stdio agent-cost -- npx -y @vk0/agent-cost-mcp

または、プロジェクトのルートにある .mcp.json に次の内容を記述して、プロジェクトスコープのサーバーを追加します。

{
  "mcpServers": {
    "agent-cost": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-cost-mcp"]
    }
  }
}

Windows ユーザー: コマンドを cmd /c で囲みます。 claude mcp add --transport stdio agent-cost -- cmd /c npx -y @vk0/agent-cost-mcp

Cursor

プロジェクトのルートに .cursor/mcp.json を作成します（グローバルにインストールする場合は ~/.cursor/mcp.json を作成します）。

{
  "mcpServers": {
    "agent-cost": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-cost-mcp"]
    }
  }
}

Cline

Cline の MCP 設定を開き（MCP Servers アイコンをクリック → 設定）、次を追加します。

{
  "mcpServers": {
    "agent-cost": {
      "command": "npx",
      "args": ["-y", "@vk0/agent-cost-mcp"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

動作確認

任意のクライアントで、「agent-cost が公開するツールは何ですか？」 と尋ねます。次のようなグループに分けられた11個のツール名が表示されるはずです。

• コストの照会：get_session_cost、get_tool_usage、get_cost_trend、get_subagent_tree
• 最適化分析：get_tool_roi、suggest_optimizations、detect_cost_anomalies
• 予測：get_cost_forecast、estimate_run_cost
• 設定：configure_budget、set_monitor_webhook

何も表示されない場合は、FAQ を参照してください。

マーケットプレイス／ディスカバリー

現在、検証済みの発見経路は次のとおりです。

• npm： npx -y @vk0/agent-cost-mcp による標準的なインストール方法
• MCP Registry： パッケージのメタデータとレジストリ上の識別情報
• Smithery： 検証済みの公開中サードパーティー掲載ページ https://smithery.ai/servers/unfucker/agent-cost-mcp
• mcp.so： 検証済みの公開中製品ページ https://mcp.so/server/agent-cost-mcp/vk0dev

Glama は、安定した製品ページの URL が再確認されるまでは、未検証として扱ってください。

マーケットプレイスのメタデータの品質は掲載先によって異なる場合がありますが、現時点では Smithery と mcp.so でこのパッケージの公開が確認されています。 オペレーターが検証する場合は、信頼できる標準の掲載先として、まず Smithery を確認してください。その後、Glama と dev.tools は公開中であると想定せず、手動で再確認する対象として扱ってください。

このパッケージを初めて見つけた場合、現時点で推奨される方法は、インストールには npm を使い、マーケットプレイス形式で閲覧するには Smithery または mcp.so を使うことです。

手軽な可視化（ネイティブの /cost、ccusage、cctally）と Cost Guard のフォレンジック分析（@vk0/agent-cost-mcp）

Claude Code、ccusage、cctally では、すでに便利なコスト可視化機能を利用できます。@vk0/agent-cost-mcp は、さらに踏み込んだフォレンジック分析、帰属分析、ガードレールを提供します。

次のような場合はネイティブの /cost、ccusage、または cctally を使います

• 現在のセッションの合計やステータスラインの数値を手早く確認したい
• 日次または期間ごとの使用状況ダッシュボードや消費ペースの概要が必要
• Pro／Max サブスクリプションのクォータ予測、パーセントあたりのコスト推移、しきい値アラート（cctally）が必要
• 人向けに洗練されたモニタリング UX を探している
• 設定不要のものが必要

@vk0/agent-cost-mcp を使う場面

• get_tool_roi と get_tool_usage で、ツールごとのコスト比率と ROI ランキングを確認したい場合
• get_subagent_tree で、ブランチをまたいだ親↔サブエージェント間のコスト配分が必要な場合
• detect_cost_anomalies で、ローカルのベースラインと照らし合わせて異常を検出したい場合
• get_cost_forecast または estimate_run_cost で、今後の支出を予測したい場合
• configure_budget で、エージェントが読み取れる予算上限と強制停止のガードレールを設定したい場合
• suggest_optimizations と set_monitor_webhook で、機械可読な次のアクションの提案と署名付き Webhook アラートが必要な場合

組み合わせて使う場合

手軽に状況を把握するには、組み込みの /cost、ccusage、または cctally を使います。次に知りたいことが「予算を消費したツール、サブエージェント、またはブランチはどれか」「実行を続けた場合どうなるか」「次にエージェントがすべきことは何か」であれば、ローカルの JSONL から機械可読な形式で答えられる @vk0/agent-cost-mcp を使います。

このパッケージは、請求書、組織全体の課金システム、または実行中のランタイムのイントロスペクションに代わるものではありません。Claude Code のセッションログを使った、構造化されたコストのフォレンジック分析とガードレールのためのローカル MCP サーフェスです。

ドキュメントとハウツーガイド

リファレンス全体ではなく、具体的な運用ワークフローを確認したい場合は、こちらから始めてください。

• セットアップ、予測、予算上限のワークフローに関する手軽なレシピが必要ですか？docs/README.md をご覧ください。
• 最新リリースの変更点：2.3.3 では、集計された日次トレンドと異常検出のベースラインがアシスタント行のタイムスタンプに基づくようになり、複数日にわたる古い JSONL ログ内の新しい日も引き続き表示されます。
• 親セッションと子セッションに支出が分散していて、ネストされた subtreeCost の仕組みを確認したい場合は、docs/subagent-tree-guide.md を開いてください。
• Claude Desktop のクイックセットアップ
• get_subagent_tree の出力の読み方
• 予算上限のレシピ：80% のソフトアラートと 100% のハード上限を使い分ける方法

すでにリリース済みのデモアセットを手早く確認できます。

• 現在の get_cost_forecast の運用例を示す予測／上限到達のデモ GIF
• 現在の get_subagent_tree のブランチ別コスト例を示すサブエージェントツリーのコストデモ GIF

ツール

11 個の MCP ツールはすべてローカルの JSONL セッションログを対象とし、Cost Guard の 1 つの問いに答えることを目指しています。つまり、支出がどこに蓄積しているか、現在のパターンにどれほどリスクがあるか、そしてオペレーターまたはエージェントが次に何を変更すべきか、という問いです。

コストクエリ（読み取り専用）：

最適化分析：

予測（支出前）：

| estimate_run_cost | プロンプト、モデル、予想されるツール呼び出しの形状に基づいて、実行前に予定された実行のコストを推定し、支出前の判断に使える信頼度付きの {low, expected, high} を返します。 |

設定（書き込み）：

| set_monitor_webhook | 異常アラート、予算しきい値の超過、暴走フラグを通知するための HMAC 署名付き Webhook 先を登録します。必要に応じて Cost Guard のシグナルをローカルセッションの外部に送信し、オペレーターのワークフローに届けられます。 |

set_monitor_webhook でローカルモニター設定の ~/.agent-cost-mcp/monitor-webhook.json に Webhook URL とシークレットの両方を保存するまで、モニターアラートは機能しません。

ローカルですばやくテストするには、まず小さな localhost レシーバーを起動し、set_monitor_webhook の送信先を http://127.0.0.1:8787/hook に設定します。

python3 - <<'PY'
from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("content-length", "0"))
        body = self.rfile.read(length).decode("utf-8", errors="replace")
        print(f"\n--- webhook {self.path} ---")
        print(body)
        self.send_response(204)
        self.end_headers()

HTTPServer(("127.0.0.1", 8787), Handler).serve_forever()
PY

Windows では、python3 が使用中のマシンの Python ランチャーではない場合、同じローカルリスナーの方法を py -3 で使用してください。

{
  "sessionPath": "~/.claude/projects/my-project/session-main.jsonl",
  "subagentPaths": [],
  "turnCount": 2,
  "totals": {
    "input_tokens": 2000,
    "output_tokens": 500,
    "cache_read_input_tokens": 100,
    "cache_creation_input_tokens": 50,
    "tool_use_count": 1,
    "tool_result_count": 1,
    "linked_tool_result_count": 1,
    "estimated_cost_usd": 0.013718
  }
}

{
  "projectPath": "~/.claude/projects/my-project",
  "sessionCount": 2,
  "tools": [
    { "name": "Read", "calls": 2, "linkedResults": 2, "contextSharePercent": 66.67 },
    { "name": "Grep", "calls": 1, "linkedResults": 0, "contextSharePercent": 33.33 }
  ]
}

{
  "projectPath": "~/.claude/projects/my-project",
  "days": 7,
  "totalCostUsd": 0.027443,
  "totalSessions": 2,
  "daily": [
    {
      "date": "2026-04-10",
      "sessions": 2,
      "costUsd": 0.027443,
      "inputTokens": 2400,
      "outputTokens": 600
    }
  ]
}

{
  "sessionPath": "~/.claude/projects/my-project/session-main.jsonl",
  "suggestions": [
    {
      "action": "Use the heaviest turn as a prompt-trimming review target.",
      "reason": "Turn 1 is the densest token consumer in this session.",
      "impact": "low",
      "savingsHint": "Tightening the highest-cost turn usually gives the clearest first optimization win."
    }
  ]
}

会話の例

You:   How much did I spend on Claude Code this week?

Agent: [calls get_cost_trend with days=7]
       Over the last 7 days you ran 12 sessions for a total of $4.82.
       Heaviest day was Wednesday at $1.47 across 4 sessions.

You:   Which tools are eating my context?

Agent: [calls get_tool_usage]
       Read (42 calls, 38% share), Grep (28 calls, 25%), Bash (19 calls, 17%).
       Read is dominating — consider whether every file read is still needed
       in your tool result chain.

You:   Any quick wins for my last session?

Agent: [calls suggest_optimizations]
       1. Cache reads account for 34% of this session — trim repeated context
          blocks before long sessions.
       2. 7 tool calls had no linked results — inspect abandoned invocations.

仕組み

  ~/.claude/projects/*.jsonl           ┌─────────────────┐
  (Claude Code session logs)  ──────▶  │  JSONL parser   │
                                       │  + pricing.ts   │
                                       └────────┬────────┘
                                                │
                                                ▼
                                       ┌──────────────────────────┐
  Agent tool call (stdio MCP)  ──────▶ │  MCP server              │ ─── JSON response
                                       │  (11 tools across query, │
                                       │   analytics, forecast,   │
                                       │   and config surfaces)   │
                                       └──────────────────────────┘

• パーサーは、Claude Code が生成する生の JSONL 行から、ターンごとの使用量フィールド（input_tokens、output_tokens、cache_read_input_tokens、cache_creation_input_tokens）を直接読み取ります。
• 料金テーブル（src/pricing.ts）には、Claude モデルの 100 万トークンあたりの料金が記載されています。default のフォールバックも用意されているため、未知のモデルでもエラーにならず、概要を表示できます。
• MCP サーバーは、標準入出力経由で型付きツールを 11 個公開し、ローカルでのコスト照会、ツール／セッションごとの分析、異常検知、実行前の予測、予算上限、Webhook アラート設定に対応します。
• デフォルトではネットワークへのデータ送信はありません。 テレメトリーも、API キーも、クラウド同期もありません。任意で外部へ送信する機能は set_monitor_webhook のみで、アラート配信のための明示的なオプトイン設定が必要です。

代替ツールとの比較

これらのツールには共通点がありますが、解決しようとする課題はそれぞれ異なります。要点として、エージェントがセッションの詳細分析、ツールごとのコスト配分、予測、異常検知、ガードレールのために直接照会できる、ローカルで MCP を優先したコストガードが必要なら、@vk0/agent-cost-mcp が適しています。主にダッシュボード、ネイティブの簡易チェック、または汎用的なコスト監視が必要なら、ほかの選択肢から試すほうが適している場合があります。

率直に言うと、いくつか注意点があります。

• 手早くネイティブな数値を確認したいだけなら、組み込みの /cost または /usage が依然として最適です。
• 詳細なセッションフォレンジックより、レポート重視の機能、ダッシュボード、サブスクリプションのクォータ確認を優先するなら、ccusage、cctally、claude-usage、または Claude-Code-Usage-Monitor のほうが適している場合があります。
• ローカルでの実行後のコストデバッグの詳細より、消費速度のライブ監視や実行中の API プログラムのラップを重視するなら、CodeBurn または tokmon のほうが適している場合があります。なお、tokmon がサポートしているのは OpenAI gpt-* モデルのみで、Claude Code や Anthropic はサポートしていません。
• @vk0/agent-cost-mcp は、ローカルの Claude Code JSONL ログ、価格を考慮したコスト分析、MCP 経由で呼び出せる出力、エージェントのループ内で得られるガードレール形式の回答に意図的に対象を絞っています。 最適な対象： ログをクラウドサービスに送信したり、別の課金ダッシュボードを開いたりせずに、エージェントに「トークンはどこに使われたのか、どのツールやブランチが原因なのか、このパターンは危険なのか、次に何を変更すべきか」と尋ねたい個人開発者や小規模チーム。

よくある質問

制限事項

• 推定値であり、請求額ではありません。 コストは、ターンごとの使用量フィールドにローカルの料金表を掛けて算出します。Anthropic の請求書の代わりにはなりません。
• 料金表は手動で更新します。 料金が変更された場合は、src/pricing.ts を更新する必要があります（意図的な設計です。ネットワークへのサイレントなアクセスは行いません）。
• Claude Code のみ対応しています。 Cursor／Cline／Continue のセッションは解析されません。要望があれば、他のクライアントにも対応する可能性があります。
• ローカルファイルの検出。 サーバーは、指定されたプロジェクトパスからファイルを読み取ります。実行中の Claude Code の状態を照会することはありません。
• 構造化された JSON 出力。 リッチなダッシュボードも、グラフも、ウェブ UI もありません。これは不具合ではなく、MCP クライアントが UI であるという設計上の特徴です。
• キャッシュ読み取りの把握はソースに依存します。 JSONL ログにキャッシュ読み取り／キャッシュ作成のトークンフィールドが含まれていない場合、それらの項目はゼロとして報告されます。

スタンドアロン CLI

同じパーサーを CLI として利用できるため、MCP クライアントなしで単発の分析を実行できます。

npx -y @vk0/agent-cost-mcp ~/.claude/projects/my-project/session.jsonl
npx -y @vk0/agent-cost-mcp session.jsonl --subagent subagent.jsonl
npx -y @vk0/agent-cost-mcp session.jsonl --watch --watch-interval 5

--watch を指定すると、一定間隔で対象セッションのログを再スキャンし、更新された簡潔なサマリーを出力します。アクティブなコーディングセッションでコストが蓄積されている間の確認に便利です。

MCP の get_session_cost ツールと同じ JSON を出力します。

開発

リポジトリをクローンして、次を実行します。

npm ci           # install deps
npm run build    # compile to dist/
npm test         # vitest unit tests
npm run lint     # tsc --noEmit
npm run smoke    # end-to-end MCP client smoke test

スタック：TypeScript、@modelcontextprotocol/sdk、Zod、Vitest。

Official MCP Registry の復旧手順

npm／パッケージのメタデータがすでに正しい状態で、Official MCP Registry の掲載情報を範囲を限定して再公開する必要がある場合は、新しいタグを作成したり、リリースフロー全体を再実行したりせず、専用の GitHub Actions ワークフローを実行します。

gh workflow run registry-republish.yml --repo vk0dev/agent-cost-mcp

このワークフローは、GitHub OIDC 経由で server.json を Official MCP Registry に再公開するだけです。npm への公開や、新しいリリースの作成は行いません。

変更履歴

CHANGELOG.md を参照してください。このプロジェクトでは v1.0.0 以降、セマンティックバージョニングを採用しています。

コントリビューション

github.com/vk0dev/agent-cost-mcp で Issue や PR を歓迎します。新しい料金情報、ログ形式の変更、追加のクライアント対応については、サンプルフィクスチャを添えて、まず Issue を作成してください。

ライセンス

MIT © vk0.dev