ollama-mcp

Anthropic バックエンドの Claude Code セッションから、Ollama バックエンドの Claude Code セッションにタスクを委譲します。2つのセッションが環境変数を共有することはありません。

ollama launch claude --model <model> は、ANTHROPIC_* 変数をシェルにエクスポートすることで動作します。そのため、通常は専用のターミナルが必要です。変数はプロセス全体に適用されるため、1つのシェルは「Anthropic」か「Ollama」のどちらか一方にしかなれず、両方にはなれません。

この MCP サーバーは、明示的に構築された環境で、委譲された各セッションを子プロセスとして起動します。Opus セッションは自身の認証情報とモデル設定を保持し、委譲先は Ollama の設定を使用します。これらは同じターミナル内で並行して実行されます。

┌────────────────────────────┐
│  Claude Code (Opus)        │   your session, Anthropic credentials
│                            │
│   └─ mcp: ollama-mcp ──────┼──▶ spawn: claude -p   (fresh env)
└────────────────────────────┘         ANTHROPIC_BASE_URL=127.0.0.1:11434
                                       ANTHROPIC_AUTH_TOKEN=ollama
                                       → qwen3.5:397b-cloud

目次

• 仕組み

• 前提条件

• インストール

• 設定

• 委譲モード

• ツールリファレンス

• 運用方法

• ジョブ成果物

• トラブルシューティング

• プラットフォームサポート

• セキュリティモデル

• 開発

Related MCP server: codex-as-mcp

仕組み

Ollama サーバーは Anthropic 互換の POST /v1/messages エンドポイントを公開しているため、Claude Code は正しいベース URL を指定すれば、変更を加えずに通信できます。委譲された各タスクは、claude -p として自身のプロセスで実行され、以下の設定が適用されます。

ANTHROPIC_BASE_URL=http://127.0.0.1:11434
ANTHROPIC_AUTH_TOKEN=ollama
ANTHROPIC_DEFAULT_OPUS_MODEL=<model>
ANTHROPIC_DEFAULT_SONNET_MODEL=<model>
ANTHROPIC_DEFAULT_HAIKU_MODEL=<model>
CLAUDE_CODE_SUBAGENT_MODEL=<model>

3つのモデルスロットはすべて同じ Ollama モデルを指すため、エイリアス（opus、sonnet、haiku）や、委譲先の内部で起動されたサブエージェントは、そのモデルに解決され、Anthropic のデフォルトに静かにフォールバックすることはありません。

子プロセスの環境は、プラットフォームごとの小さな許可リストから構築されます。ANTHROPIC_*、CLAUDE_*、AWS_*、GOOGLE_*、AZURE_*、OPENAI_*、BEDROCK_*、VERTEX_* に一致するものはすべて、Ollama の値が適用される前に削除されるため、シェル内の紛れ込んだ ANTHROPIC_API_KEY が委譲された実行に漏洩したり、課金されたりすることはありません。

また、委譲先は --strict-mcp-config と MCP 設定なしで起動されるため、起動が高速になり、このサーバーを再帰的に呼び出すことを防ぎます。

前提条件

インストール前に各コンポーネントを確認してください:

node --version                              # v20 or newer
claude --version
curl -s http://127.0.0.1:11434/api/version  # {"version":"..."}
ollama list                                 # at least one model

クラウドモデル vs ローカルモデル。 :cloud タグが付いたモデルは Ollama のインフラストラクチャ上で実行され、ollama signin が必要です。これらは、ほとんどのラップトップのメモリに収まるものよりもはるかに高性能であり、委譲の実用的な選択肢となります。ローカルモデルも動作し、マシンからデータが外部に出ることはありません。

インストール

npm から（推奨）

クローンやビルドは不要 — npx が必要に応じて取得します:

claude mcp add ollama --scope user -- npx -y claude-ollama-delegate-mcp

または、グローバルにインストールします。これにより、設定 CLI も PATH に追加されます:

npm install -g claude-ollama-delegate-mcp
claude mcp add ollama --scope user -- claude-ollama-delegate-mcp

ソースから

git clone https://github.com/histonedev/claude-ollama-delegate-mcp.git
cd claude-ollama-delegate-mcp
npm install          # builds automatically via the prepare script
claude mcp add ollama --scope user -- node "$(pwd)/dist/index.js"

設定 CLI は node dist/cli.js … として実行するか、npm link を使用して ollama-mcp-config を PATH に追加します。

スコープ

--scope user はすべてのプロジェクトで利用可能にします。--scope project は現在のリポジトリの .mcp.json に書き込み、コラボレーターと共有します。--scope local はこのマシンとプロジェクトに限定します。

確認

claude mcp list        # ollama: ... - ✔ Connected

その後、Claude Code セッションを再起動してください — ツールリストは起動時に読み込まれます。

設定

設定は4つのレイヤーから解決され、後続のものが優先されます:

1. 組み込みのデフォルト

2. ユーザー設定 — ~/.ollama-mcp/config.json（$OLLAMA_MCP_CONFIG でパスを上書き可能）

3. プロジェクト設定 — サーバーの作業ディレクトリ内の ./ollama-mcp.config.json

4. 環境変数

{
  "delegationMode": "ondemand",
  "allowedModels": ["qwen3.5:397b-cloud", "gemma4:31b-cloud"],
  "defaultModel": "qwen3.5:397b-cloud",
  "defaultPermissionMode": "auto",
  "baseUrl": "http://127.0.0.1:11434",
  "claudeBin": "claude",
  "stateDir": "~/.ollama-mcp/jobs",
  "jobTimeoutMs": 1800000,
  "maxInlineChars": 60000
}

設定の変更

設定はターミナルから変更され、モデルによって変更されることはありません:

ollama-mcp-config                              # show current settings + active layers
ollama-mcp-config --mode auto                  # off | ondemand | auto
ollama-mcp-config --allow qwen3.5:397b-cloud   # or: --allow all
ollama-mcp-config --default-model qwen3.5:397b-cloud
ollama-mcp-config --permission-mode acceptEdits
ollama-mcp-config --scope project              # write ./ollama-mcp.config.json

その後、Claude Code セッションを再起動して、サーバーが設定を再読み込みするようにします。

これを実現する MCP ツールは意図的に存在しません。 セキュリティモデル を参照してください。

許可されたモデル

allowedModels: []（デフォルト）は、サーバーが提供する任意のモデルを許可します。空でないリストの場合:

• delegate_start は、リスト外のモデルを拒否し、静かに別のモデルに置き換えるのではなく、許可されたセットを指定します

• ollama_models は、除外されたモデルを BLOCKED by allowedModels とマークします

• 許可リストは delegate_start ツールの説明に埋め込まれるため、オーケストレーターは追加の呼び出しなしで選択肢を把握できます

• CLI は、defaultModel が新しいリストの外側に取り残されるような変更を拒否します

委譲モード

これは、モデルが実際に読み取るツールの説明を書き換えることで、オーケストレーターが委譲にどの程度積極的に頼るかを制御します。変更にはセッションの再起動が必要です（設計上の意図です）。

auto モードでは、説明はオーケストレーターに対し、自己完結型で、安価に検証可能で、コンテキストを多く消費する作業（大量のファイル要約、最初のパス検索、機械的なリファクタリング、ボイラープレートとテストの足場、ログや差分のトリアージ）を委譲し、アーキテクチャ上の決定、セキュリティに関わる変更、曖昧な要件、最終レビューは自身で保持するように指示します。また、運用方法 で説明されている理由から、委譲された主張を検証するように指示されています。

ツールリファレンス

delegate_start

delegate_followup は job_id または session_id を受け取り、同じ prompt/prompt_file ペアとオプションの permission_mode、max_turns、wait_seconds を受け取ります。

運用方法

デフォルトで非同期

delegate_start はミリ秒単位で job_id を返します。委譲先はバックグラウンドで実行を続けます。これにより、長時間のタスクがセッションを停止させたり、MCP クライアントのタイムアウトを発生させたりするのを防ぎます。

delegate_start({ prompt: "Audit src/ for unused exports" })
  → job_id A, session_id S, turn 1, state: running

delegate_status({ job_id: "A" })
  → recent activity:
      [tool] Grep: export
      [tool] Read: /repo/src/index.ts

delegate_result({ job_id: "A" })
  → the final text

これらのいずれかに wait_seconds を渡すと、代わりにブロックします — ポーリングの往復がもったいない短いタスクに便利です。

双方向の会話

すべてのジョブには session_id が含まれています。その job_id を delegate_followup に渡すと、完全な履歴でセッションが再開されます。session_id はターン間で安定していますが、各ターンは新しい job_id を取得します。

delegate_start({ prompt: "Summarise the auth flow in this repo" })
  → job A, session S, turn 1
delegate_followup({ job_id: "A", prompt: "Now list every place it can fail" })
  → job B, session S, turn 2   (delegate still remembers turn 1)

委譲先がすでに関連するコンテキストを読み込んでいる場合、フォローアップは新しく開始するよりもはるかに低コストです。

長いプロンプト

すべてのプロンプトパラメータには、対応する prompt_file があります。内部的には、プロンプトは常にディスクに書き込まれ、CLI に stdin 経由で渡されます — argv エントリとしてもシェル経由でもありません。バッククォート、$(...)、引用符、改行、グロブ文字はそのまま通過し、argv の長さ制限もありません。

delegate_start({ prompt_file: "/tmp/refactor-brief.md" })

権限

デリゲートはデフォルトで defaultPermissionMode (auto) になります。特定の呼び出しを絞り込む場合：

// read-only review
delegate_start({ prompt: "...", disallowed_tools: ["Write", "Edit", "NotebookEdit"] })

// tightly scoped
delegate_start({ prompt: "...", allowed_tools: ["Read", "Grep", "Glob"] })

委任された出力の信頼性

完了したすべての結果は、その ツール呼び出し回数 を報告します。弱いモデルは、何も実行せずに自信満々に答えることがあります — 開発中、あるモデルは Bash を呼び出さずに環境変数が設定されていないと主張しましたが、促されるとコマンドを実行して正しい値を報告しました。

tool calls: 0 の結果は、未検証として注釈されます：

tool calls: 0   <- answered without using any tools; treat factual claims as unverified

delegate_status は実際のトレースを示します。純粋に会話ベースのフォローアップは正当にゼロになることがあります — このフラグは「これを裏付けるものは何もない」という意味であり、「何かが壊れた」という意味ではありません。

キャンセル

delegate_cancel({ job_id: "A" })

デリゲート とそれが開始したすべてのもの を強制終了します。そのため、長いビルドの途中だったデリゲートがビルドを実行したままになることはありません。

ジョブアーティファクト

各ジョブは ~/.ollama-mcp/jobs/<job_id>/ に書き込みます：

maxInlineChars より長い結果はツール応答で切り詰められ、全文は result.txt から読み取られます。自動的に削除されることはありません — 好きなときにディレクトリを削除してください。

トラブルシューティング

Cannot reach Ollama at http://127.0.0.1:11434 Ollama が実行されていません。ollama serve を起動するか、デスクトップアプリを開いてください。別の場所で待機している場合は、OLLAMA_MCP_BASE_URL を設定してください。

No models available from Ollama ollama pull qwen3.5:397b-cloud を実行し、:cloud モデルには ollama signin を行ってください。

<model> was retired at … (HTTP 410) Ollama がそのクラウドモデルを削除しました。ollama list には、削除されたモデルのローカルキャッシュマニフェストがまだ表示されることがあります — 実際に動作するものを確認し、defaultModel を更新してください。

Model "x" is not in the allowed list 意図した動作です。ollama-mcp-config --allow <models> を実行し、その後再起動してください。

ツールが Claude Code に表示されない ツールリストはセッション開始時に読み取られます。再起動するか、claude mcp list で確認してください。

デリゲートが起動エラーで即座に失敗する CLI が見つかりませんでした。OLLAMA_MCP_CLAUDE_BIN に claude の絶対パスを設定してください。

すべてが遅い クラウドモデルはターンごとにラウンドトリップを支払い、Claude Code はすべてのリクエストで大きなシステムプロンプト（約25kトークン）を送信します。max_turns を使用してエージェントループを制限し、allowed_tools を使用してデリゲートが必要以上に探索するのを防いでください。

プラットフォームサポート

プラットフォームの違いは src/platform.ts に分離されています：

バイナリ解決。 POSIX では、spawn が PATH を検索します。Windows では、ネイティブインストールは claude.exe を提供し、npm インストールは claude.cmd を提供しますが、CreateProcess はそれを直接実行できません — そのためサーバーは PATH × PATHEXT を走査して .exe を優先し、.cmd シムを cmd.exe 経由でルーティングするフォールバックを行います。

引数のエスケープ。 そのフォールバックは2つのレイヤーを適用します：MSVCRT argv の引用符付け、次に cmd 自身のメタ文字（& | < > ^ " ( ) % !）をキャレットでエスケープします。2番目のレイヤーをスキップすることは、古典的な .cmd コマンドインジェクションの穴です。プロンプトはこのパスには決して触れません — それらは stdin を経由します。1つの制限：複数行 の append_system_prompt は cmd.exe のコマンドラインをまたげないため、サーバーはそれを静かに壊す代わりに、OLLAMA_MCP_CLAUDE_BIN を指す明確なエラーを発生させます。

環境許可リスト。 Windows は POSIX よりもはるかに多くのセットを保持します。SystemRoot と windir はオプションではありません — それらを削除すると Winsock の初期化に失敗し、子プロセスはローカルホストに対してもソケットを開けなくなります。名前は大文字小文字を区別せずに一致しますが、親の元のスペルでコピーされます。

キャンセル。 POSIX の子プロセスはプロセスグループリーダーとして detached で生成され、process.kill(-pid) でキャンセルされます。Windows では taskkill /T /F を使用します。どちらの場合でも、デリゲート自身のサブプロセスはデリゲートとともに終了します。サーバーはシャットダウン時にも実行中のデリゲートを強制終了します。

セキュリティモデル

認証情報の分離がポイントです。 子環境は継承されるのではなく、ゼロから構築され、プロバイダ変数は Ollama の値が適用される前に削除されます。これは test/env-unit.mjs でカバーされ、test/e2e.mjs は親に偽の ANTHROPIC_API_KEY を注入し、それがデリゲートに到達しないことをアサートします。

委任ポリシーはモデルから書き換えられません。 delegationMode や allowedModels を変更する MCP ツールはありません。以前のバージョンにはありましたが、それは間違いでした：ondemand が不便だと感じたモデルは、1回の呼び出しで auto に切り替えて自由に委任できてしまいます。設定は起動時に一度だけ読み込まれ、実行時に変更されることはなく、ツールの説明にはポリシーはモデルが変更できるものではないと明記されています。

これはガードレールであり、セキュリティ境界ではありません。 シェルアクセスを持つエージェントは、設定ファイルを編集できます。ツールを削除することで得られるのは、そのような変更が 次回の再起動まで有効にならない、目に見えるファイル編集 となり、タスク途中の1回の静かなツール呼び出しではなくなることです。完全に堅牢にするには、MCP 登録時に --env で値を固定します。これにより設定ファイルが上書きされます：

claude mcp add ollama --scope user \
  --env OLLAMA_MCP_DELEGATION_MODE=ondemand \
  --env OLLAMA_MCP_ALLOWED_MODELS=qwen3.5:397b-cloud \
  -- node /path/to/claude-ollama-delegate-mcp/dist/index.js

デリゲートはあなたのファイルシステムを継承します。 デリゲートは、あなたが指定した cwd で、defaultPermissionMode であなたのユーザーとして実行されます。委任されたセッションは、他の Claude Code セッションと同様に扱ってください — 信頼性の低いモデルに作業を任せる場合は、disallowed_tools または読み取り専用の権限モードを使用してください。

開発

npm install        # installs and builds
npm run build      # tsc
npm run dev        # tsc --watch

テスト

node test/env-unit.mjs       # env isolation: no secret leaks, platform vars present
node test/quoting.mjs        # Windows argv/cmd escaping, incl. an injection probe
node test/killtree-unit.mjs  # process-tree termination
node test/e2e.mjs            # full MCP round trip           (needs Ollama running)
node test/async.mjs          # async polling, prompt_file, cancel  (needs Ollama)
CFG_PATH=/tmp/c.json CFG_CWD=/tmp node test/readonly.mjs   # config is read-only to the model

npm test は、ネットワークを必要としない3つのテストを実行します。

リリースの公開

npm login                       # interactive, once per machine
npm version patch               # or minor / major -- tags and bumps
npm publish                     # prepare script builds first
git push --follow-tags

パッケージは claude-ollama-delegate-mcp で、dist/、README.md、LICENSE のみを出荷します。publishConfig.access は public で、prepare はパッケージング前に tsc を実行するため、古い dist/ が公開されることはありません。出荷前に npm pack --dry-run で tarball をプレビューしてください。

レイアウト

ライセンス

MIT — LICENSE を参照してください。