mcp-llm-offload

Claude（や任意の MCP クライアント）の軽量な LLM 作業を、自分で管理するモデル — ローカル LLM（LM Studio・Ollama・llama.cpp）や OpenAI 互換の任意プロバイダ（OpenRouter・xAI Grok・OpenAI・Groq・Together など）— にオフロードする MCP サーバーです。安価で重要度の低い処理に、フロンティアモデルのクォータを浪費せずに済みます。

なぜ

フロンティアモデルは強力ですが、エージェントの日常作業の多くは軽量です。ログの要約、チケットの分類、テキストからのフィールド抽出、一文の言い換え——こうした処理にフロンティアモデルの料金（とクォータ）を払うのは無駄です。

mcp-llm-offload は、これらのタスクをあなたが選んだバックエンドへ転送する MCP ツールを少数だけ公開します。LM Studio・Ollama・llama.cpp・OpenRouter・Grok・OpenAI・Groq・Together はすべて同じ /v1/chat/completions API を話すため、この小さなサーバー 1 つですべてに対応できます。バックエンドは環境変数で切り替えられ、呼び出しごとに上書きすることも可能です。

機能

• 🔀 プロバイダ非依存 — サーバーは 1 つ、相手は任意の OpenAI 互換エンドポイント。主要なものはプリセット済み、それ以外は自分で追加できます。

• 🏠 ローカルファースト — 既定はローカルの LM Studio。ローカルバックエンドなら API キー不要です。

• 🎯 目的特化のツール — ask・summarize・classify・extract・health。素のチャット中継ではなく、軽量タスク向けに整形されています。

• 🧭 呼び出しごとのルーティング — 各ツールは provider と model を任意で受け取ります。安価な処理はローカルへ、少しだけ難しい処理は再設定なしで Grok / OpenRouter へ回せます。

• 📂 ファイル入力 — summarize/classify/extract は path（ファイルまたは glob）を受け取り、サーバーがローカルで読み込みます。呼び出し側はパスだけを送るため、大きな入力のオフロードで実際にトークンを節約できます。

• 🩺 実用的なエラー — 接続・タイムアウト・認証・モデル 404・レート制限の失敗は、スタックトレースではなく「次にこうすればよい」という平易な文字列で返ります。

• 📦 単一ファイル・インストール不要 — PEP 723 のインライン依存により uv run llm_offload_mcp.py だけで動きます。

• 🤖 Claude Code サブエージェント同梱 — 軽量作業を自動で振り分ける llm-offloader エージェントを任意で利用できます。

推奨ローカルモデル

軽量なオフロード作業に大きなモデルは要りません。要約・分類・短い書き換えには 0.6b〜2b クラスの指示チューニング済みモデルで十分です。おすすめの既定値:

Apple Silicon では LM Studio の MLX ビルド（例: gemma-4-e2b-it-mlx）を推奨します。同クラスの Qwen・Llama・Phi 系でも同等に動作します。バックエンドが提供する ID を LLM_MODEL に設定してください。

対応プロバイダ

カスタムプロバイダは好きな名前で使えます。FOO_BASE_URL（必要なら FOO_API_KEY）を設定し、ツールを provider="foo" で呼び出してください。

仕組み

Claude Code ──stdio──▶ mcp-llm-offload ──HTTP /v1/chat/completions──▶ バックエンド
 (フロンティア)          (このサーバー)                                (ローカル / Grok / OpenRouter …)

このサーバーは薄く行儀のよい MCP フロントエンドです。使用するバックエンドとモデルを解決し（呼び出し → 環境変数 → プリセットの順）、テンプレート互換性を最大化するためにシステム指示をユーザーターンに畳み込み、エンドポイントを呼び出して、きれいなテキスト（または Error: … 文字列）を返します。

上の図は、これによって実現できる全体像です。小さなローカルモデルが自律的な「忍者」として日常的な雑務を端から端まで処理し、そのために Claude が一切呼ばれない、という構図です。

クイックスタート

1. 前提条件

• uv（推奨）。または pip の使える Python 3.10+。

• バックエンド: 起動中のローカルサーバー（例: LM Studio → Developer ▸ Start Server）、またはホスト型プロバイダの API キー。

2. 取得

git clone https://github.com/jonpol01/mcp-llm-offload.git
cd mcp-llm-offload

起動を確認します（MCP を stdio で提供するため、クライアントを待って待機します。Ctrl-C で終了）:

uv run llm_offload_mcp.py

uv がない場合は pip install mcp httpx のあと python llm_offload_mcp.py。

3. Claude Code への登録

ここで指定したサーバー名がツールの接頭辞（mcp__<name>__ask …）になります。同梱サブエージェントは名前 offload を前提とするため、エージェントを編集しない限りこの名前を使ってください。

ローカル LM Studio（別マシンで動かす場合は LAN ホストを指定）:

claude mcp add offload \
  -e LLM_PROVIDER=lmstudio \
  -e LMSTUDIO_BASE_URL=http://localhost:1234/v1 \
  -e LLM_MODEL=gemma-4-e2b-it \
  -- uv run /absolute/path/to/llm_offload_mcp.py

OpenRouter:

claude mcp add offload \
  -e LLM_PROVIDER=openrouter \
  -e OPENROUTER_API_KEY=sk-or-... \
  -e LLM_MODEL=meta-llama/llama-3.3-70b-instruct \
  -- uv run /absolute/path/to/llm_offload_mcp.py

xAI Grok:

claude mcp add offload \
  -e LLM_PROVIDER=grok \
  -e XAI_API_KEY=xai-... \
  -e LLM_MODEL=grok-2-latest \
  -- uv run /absolute/path/to/llm_offload_mcp.py

JSON 形式の MCP 設定（.mcp.json、Claude Desktop など）でも同等です:

{
  "mcpServers": {
    "offload": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/llm_offload_mcp.py"],
      "env": {
        "LLM_PROVIDER": "lmstudio",
        "LMSTUDIO_BASE_URL": "http://localhost:1234/v1",
        "LLM_MODEL": "gemma-4-e2b-it"
      }
    }
  }
}

4. 動作確認

Claude Code で health ツールを実行（または Claude に頼む）してください。解決されたプロバイダ・ベース URL・バックエンドが報告するモデル一覧が表示されます。

ツール

生成系ツールはいずれも provider と model を受け取り、その 1 回の呼び出しに限り既定を上書きできます。

ファイル入力（オフロードが実際に節約になる箇所）

summarize・classify・extract は、インラインの text の代わりに path（ファイルパスや glob。例: logs/run.txt、src/**/*.py）を受け取れます。ask は path を追加の文脈として受け取ります。サーバーがファイルを自分で読み込むため、呼び出し側はパスだけを送ります。大きな入力では、ペイロードを転送するためにオーケストレータの出力トークンを払わずに済み、これがまさに狙いです。

• glob が複数一致した場合は、各ファイル名のヘッダ付きで連結されます。

• 上限: OFFLOAD_MAX_FILES（既定 50）と OFFLOAD_MAX_CHARS（既定 100000）。超過時は明確なエラーを返します。

• 読み込みはサーバープロセスのファイル権限で行われます。クラウドプロバイダを指定している場合、ファイル内容はそのプロバイダへ送信される点に注意してください。重要なファイルはローカルバックエンドで処理してください。

トークン削減

オフロードがフロンティアのトークンを節約できるのは特定の形のときだけですが、得をするときは大きく得をします。原則は、呼び出し側が送るものも受け取るものも少ないときに節約になる、です。つまり生成（小さなプロンプト → 大きな出力）と、path によるファイル入力（ペイロードではなくパスだけを送る）。小さな入力をインラインで丸投げすると、自分でやるより高くつきます——それはフロンティアモデルで、バッチで、あるいは自律実行で。

* 重み付けユニット（出力は入力の約 5 倍で計上、実コスト比に基づく）。フロンティアモデルがインラインで処理する場合との比較。削減量は規模に比例し、path で渡すファイルが大きいほど、呼び出し側がそれを読み込まないため削減も大きくなります。フロンティアモデルを介さない（自律実行）場合、削減は 100% です。

設定

設定はすべて環境変数で行います。既定（ローカル LM Studio）で問題なく、model を呼び出しごとに渡すなら、必須の変数はありません。

コピペ用のひな形は .env.example を参照してください。

Claude Code サブエージェント（任意）

agents/llm-offloader.md は、軽量作業をこのサーバーへ積極的に振り分け、重い処理や正確性が重要な処理はメインエージェントへ戻す、すぐ使えるサブエージェントです。小さなディスパッチモデル（sonnet、より安く済ませるなら haiku）で動くため振り分けはフロンティアモデルよりずっと安く、実作業はあなたのバックエンドに載ります。

# ユーザー全体
cp agents/llm-offloader.md ~/.claude/agents/
# またはプロジェクト単位
mkdir -p .claude/agents && cp agents/llm-offloader.md .claude/agents/

tools: は mcp__offload__* を参照するため、サーバーを名前 offload で登録しておく必要があります。

ティアリング: ローカル → Sonnet → フロンティア

オフローダーはシンプルなコスト階層のローカル層です。同梱の mid-tier サブエージェントと組み合わせると、フロンティアモデルに対して 3 層のルーティングが得られます。

mid-tier 層はバックエンド不要です — Claude（Sonnet）上で直接動くため、ローカルや OpenAI 互換のオフロードプロバイダが未設定でも機能します。よいパターン: フロンティアモデルが大きな機械的読み取り（例: 複数ファイルの API 仕様からの抽出）を mid-tier に委譲し、実装に使う部分だけをスポットチェックする — まとまった作業は安く、要となる詳細は検証済みのまま。

cp agents/mid-tier.md ~/.claude/agents/

トラブルシューティング

開発

uvx ruff check .          # lint
uv run --with mcp --with httpx python -c \
  "import importlib.util as u; s=u.spec_from_file_location('m','llm_offload_mcp.py'); m=u.module_from_spec(s); s.loader.exec_module(m); print('ok', m.mcp.name)"

CI（GitHub Actions）は、push と PR のたびに同じ lint とインポートのスモークテストを実行します。

コントリビュート

Issue・PR を歓迎します。サーバーは単一ファイル・プロバイダ中立を保ってください。新しいプロバイダは通常 PROVIDERS レジストリに 1 行追加するだけです。

ライセンス

MIT © John Paul Soliva