# Claude Token Saver Mcp

> MCP server that offloads routine coding tasks to local LLM (Ollama) to save Claude API tokens

- **Type:** MCP server
- **Install:** `agentstack add mcp-blackfoil-claude-token-saver-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BlackFoil](https://agentstack.voostack.com/s/blackfoil)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.3.2
- **License:** Apache-2.0
- **Upstream author:** [BlackFoil](https://github.com/BlackFoil)
- **Source:** https://github.com/BlackFoil/claude-token-saver-mcp

## Install

```sh
agentstack add mcp-blackfoil-claude-token-saver-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[English](./README.en.md) | 日本語

[](https://github.com/BlackFoil/claude-token-saver-mcp/actions) [](https://www.npmjs.com/package/claude-token-saver-mcp) [](https://github.com/BlackFoil/claude-token-saver-mcp/actions) [](./LICENSE)

# claude-token-saver-mcp

  

> **Beta** — 個人利用向け。736 テスト / カバレッジ 97%。

**Claude Code の「それ、ローカルでよくない？」を自動化する MCP サーバー。**

ボイラープレート生成、テスト作成、テキスト要約 — Cloud API に投げるまでもない定型タスクを、手元の [Ollama](https://ollama.com/) でさばきます。セキュリティ対策込み。

## モチベーション

Claude Code の API 利用を分析してみたら、**リクエストの約 40% は定型的なコード生成やテキスト処理**でした。この手のタスクは 7B クラスのローカルモデルでも実用的な品質が出ます。「推論は Cloud、作業は Local」— この振り分けを MCP で自動化したのがこのツールです。

## ローカル LLM はどこまで来たか

ローカル LLM の進化は速いです。2024 年の Llama 3 から 2025 年の Qwen3 まで、わずか 1 年でコード生成ベンチマーク ([HumanEval](https://arxiv.org/abs/2107.03374)) のスコアは **60% → 85%** に跳ね上がりました。

この調子なら、Agent ワークフローにローカル LLM が当たり前に組み込まれる日もそう遠くないでしょう。claude-token-saver-mcp は **Cloud と Local を使い分けるための土台**を提供します。

## しくみ

[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) は Claude Code が外部ツールを呼び出すための標準プロトコルです。このサーバーを登録すると、Claude Code が**タスクの内容を見て、定型的な処理を自動的にローカル LLM へ回します**。

```text
Claude Code ──MCP──▶ token-saver ──HTTP──▶ Ollama (ローカル)
     │                                         │
     │  「定型タスクだ → ローカルに振ろう」        │
     │                                         │
     └─── 高度な推論・設計判断は Cloud で継続 ───┘
```

Ollama が落ちていたり応答が遅い場合は Cloud API にフォールバック可能です。

## 30 秒セットアップ

**前提:** [Node.js 20+](https://nodejs.org/) と [Ollama](https://ollama.com/) がインストール済みであること。

**0.** Ollama を起動

```bash
ollama serve
```

**1.** プロジェクトルートに `.mcp.json` を作成

```json
{
  "mcpServers": {
    "token-saver": { "command": "npx", "args": ["-y", "claude-token-saver-mcp"] }
  }
}
```

**2.** Claude Code を起動して、こう頼む

```text
コーディング用にローカルLLMをセットアップして
```

RAM に応じた最適モデルが推奨 → ダウンロード（約 4GB）→ プリロードまで自動で走ります。

**3.** 動作確認

```text
TypeScript で配列をシャッフルする関数を書いて
```

「ローカルLLM（qwen2.5-coder:…）で生成しました」のようにローカルモデル名が表示されれば OK。
出ない場合は `ollama list` でモデルを確認し、[トラブルシューティング](./docs/user/troubleshooting.md) を参照してください。

ソースからビルドする場合

```bash
git clone https://github.com/BlackFoil/claude-token-saver-mcp.git
cd claude-token-saver-mcp
npm ci && npm run build
```

プロジェクトルートの `.mcp.json` に追加：

```json
{
  "mcpServers": {
    "token-saver": {
      "command": "node",
      "args": ["/path/to/claude-token-saver-mcp/dist/server.js"]
    }
  }
}
```

## 特徴

- **ローカル完結** — 定型タスクは Cloud API を使わずに処理できる
- **自動モデル選択** — RAM を検出して最適なモデルを推奨・DL・プリロード（`auto_setup`）
- **セキュリティ内蔵** — プロンプトインジェクション検知 + 出力サニタイズ
- **コスト可視化** — 節約額をリアルタイムで追跡（定型タスク比率 40% なら月 $50〜80 程度の削減が目安）
- **Cloud フォールバック** — Ollama が落ちても Cloud に自動切り替え可能

## 使用例

```text
あなた: 「ソート関数を書いて」    → offload_work がローカルで生成     💰 $0.02 節約
あなた: 「このログを要約して」    → compress_context がローカルで圧縮  💰 $0.05 節約
あなた: 「コスト節約を見せて」    → cost_dashboard: 累計 $47.89 節約
あなた: 「3つのAPIを一括実装して」 → batch_offload: 3 タスクを順次処理
```

## ローカル品質の実際

ローカル 7B モデルの出力は Claude に及びません。それは前提です。ただ、定型タスクに限れば十分実用的です。

| タスク | ローカル品質 | 向き不向き |
|:---|:---:|:---:|
| ボイラープレート生成 | ★★★★☆ | ✅ 得意 |
| ユニットテスト作成 | ★★★★☆ | ✅ 得意 |
| テキスト要約 | ★★★★☆ | ✅ 得意 |
| 単純なリファクタリング | ★★★☆☆ | ✅ 実用的 |
| アーキテクチャ設計 | ★★☆☆☆ | ❌ Cloud に任せるべき |
| 複雑なデバッグ | ★★☆☆☆ | ❌ Cloud に任せるべき |

Claude Code がタスクの複雑さを判断して自動で振り分けます。ローカルの品質が足りなければ Cloud で処理されます。

## 自動ティアリング

| RAM | Tier | モデル | DL サイズ |
|:---:|:---:|:---|:---:|
|  48 GB | Ultra | qwen2.5-coder:32b | ~18 GB |

## ツール一覧

| ツール | 説明 |
|:---|:---|
| `offload_work` | コード生成・リファクタリングをローカルで実行 |
| `compress_context` | 長大なテキストをローカルで要約 |
| `auto_setup` | 最適モデルの推奨 → DL → プリロードをワンステップで |
| `batch_offload` | 複数タスクを一括投入（順次 / 並列） |
| `cost_dashboard` | 累計節約額・モデル使用統計 |

その他のツール（6 件）

| ツール | 説明 |
|:---|:---|
| `get_metrics` | サーバーメトリクス（JSON / Prometheus） |
| `recommend_model` | タスクカテゴリ別の最適モデル推奨 |
| `pull_model` | Ollama モデルのダウンロード |
| `preload_model` | VRAM へのプリロード |
| `list_loaded_models` | ロード中モデルの一覧 |
| `configure_model_selector` | モデルセレクターのランタイム設定 |

## セキュリティ

ローカル LLM への入出力を自動で保護します。

- **プロンプトインジェクション検知** — 5 カテゴリ・20 パターンで悪意ある入力をブロック
- **出力サニタイズ** — API キー・パスワード・JWT など 11 パターンを `[REDACTED]` に置換
- **データプライバシー** — 全処理がローカル完結。外部への送信なし

## ドキュメント

| | |
|:---|:---|
| [クイックスタート](./docs/user/quickstart.md) | 5 分で始める |
| [ユースケース集](./docs/user/use-cases.md) | 具体的な活用例 |
| [設定リファレンス](./docs/user/configuration.md) | 全設定項目 |
| [FAQ](./docs/user/faq.md) | よくある質問 |
| [トラブルシューティング](./docs/user/troubleshooting.md) | エラー対応 |

## アーキテクチャ

```text
src/
├── server.ts          # MCP エントリポイント（11 ツール登録）
├── tools/             # offload_work, compress_context, auto_setup, batch_offload 等
├── ollama/            # Ollama クライアント & マルチノードロードバランサー
├── queue/             # FIFO キュー & 優先度キュー（URGENT/HIGH/NORMAL/LOW）
├── model-selector/    # モデル推奨エンジン, ベンチマーク DB, 実行トラッカー
├── validators/        # 入力バリデーション & プロンプトインジェクション検知
├── cost/              # コスト計算 & レポーター
├── metrics/           # Prometheus メトリクス収集
├── persistence/       # ExecutionTracker / BenchmarkStore のファイル永続化
├── config/            # Zod 設定スキーマ & ローダー
├── tiering/           # RAM ベースの自動ティアリング
├── logging/           # 構造化ログヘルパー
└── errors.ts          # CTS-XXXX エラー体系
```

## 開発

```bash
npm ci
npm test             # 736 テスト（カバレッジ 97%）
npm run typecheck    # 型チェック
npm run lint         # ESLint
npm run build        # プロダクションビルド
```

**対応プラットフォーム:** macOS / Linux / Windows（Ollama が動く環境）

コントリビューション歓迎です → [CONTRIBUTING.md](./CONTRIBUTING.md)

## ライセンス

[Apache License 2.0](./LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BlackFoil](https://github.com/BlackFoil)
- **Source:** [BlackFoil/claude-token-saver-mcp](https://github.com/BlackFoil/claude-token-saver-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **0.3.2** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-blackfoil-claude-token-saver-mcp
- Seller: https://agentstack.voostack.com/s/blackfoil
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.