ollama-mcp

Delegate tasks from an Anthropic-backed Claude Code session to Ollama-backed Claude Code sessions — without the two ever sharing environment variables.

ollama launch claude --model <model> works by exporting ANTHROPIC_* variables into your shell. That is why it normally needs its own terminal: the variables are process-wide, so one shell is either "Anthropic" or "Ollama", never both.

This MCP server spawns each delegated session as a child process with an explicitly constructed environment. Your Opus session keeps its own credentials and model settings; the delegate gets Ollama's. They run side by side in the same terminal.

┌────────────────────────────┐
│  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

Contents

• How it works

• Prerequisites

• Installation

• Configuration

• Delegation modes

• Tool reference

• Operating it

• Job artifacts

• Troubleshooting

• Platform support

• Security model

• Development

Related MCP server: codex-as-mcp

How it works

Ollama's server exposes an Anthropic-compatible POST /v1/messages endpoint, so Claude Code can talk to it unmodified if pointed at the right base URL. Each delegated task runs as claude -p in its own process with:

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>

All three model slots point at the same Ollama model so that aliases (opus, sonnet, haiku) and any subagent spawned inside the delegate resolve to it, rather than silently falling back to an Anthropic default.

The child environment is built from a small per-platform allowlist. Anything matching ANTHROPIC_*, CLAUDE_*, AWS_*, GOOGLE_*, AZURE_*, OPENAI_*, BEDROCK_*, VERTEX_* is dropped before the Ollama values are applied, so a stray ANTHROPIC_API_KEY in your shell cannot leak into — or bill — a delegated run.

Delegates also start with --strict-mcp-config and no MCP config, which keeps their startup fast and stops them from recursively calling this server.

Prerequisites

Verify the pieces before installing:

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

Cloud vs local models. Models tagged :cloud run on Ollama's infrastructure and require ollama signin; they are far more capable than what most laptops fit in memory, which makes them the practical choice for delegation. Local models work too and never leave your machine.

Installation

From npm (recommended)

No clone or build required — npx fetches it on demand:

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

Or install it globally, which also puts the settings CLI on your PATH:

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

From source

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"

Run the settings CLI as node dist/cli.js …, or npm link to get ollama-mcp-config on your PATH.

Scopes

--scope user makes it available in every project; --scope project writes to .mcp.json in the current repo and shares it with collaborators; --scope local keeps it to this machine and project.

Confirm

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

Then restart your Claude Code session — the tool list is read at startup.

Configuration

Settings resolve from four layers, later winning over earlier:

1. built-in defaults

2. user config — ~/.ollama-mcp/config.json (override the path with $OLLAMA_MCP_CONFIG)

3. project config — ./ollama-mcp.config.json in the server's working directory

4. environment variables

{
  "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
}

Changing settings

Settings are changed from a terminal, never by the model:

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

Then restart your Claude Code session so the server re-reads its config.

There is deliberately no MCP tool for this. See Security model.

Allowed models

allowedModels: [] (the default) permits any model the server offers. With a non-empty list:

• delegate_start rejects a model outside it, naming the allowed set rather than silently substituting one

• ollama_models marks excluded models BLOCKED by allowedModels

• the allowed list is embedded in the delegate_start tool description, so the orchestrator knows the menu without an extra call

• the CLI refuses a change that would strand defaultModel outside the new list

Delegation modes

This controls how eagerly the orchestrator reaches for delegation, by rewriting the tool descriptions the model actually reads. Changing it requires a session restart, by design.

In auto mode the description tells the orchestrator to delegate work that is self-contained, cheaply verifiable and context-hungry — bulk file summarisation, first-pass searches, mechanical refactors, boilerplate and test scaffolding, log or diff triage — while keeping architecture decisions, security-sensitive changes, ambiguous requirements and final review for itself. It is also told to verify delegated claims, for the reason in Operating it.

Tool reference

delegate_start

delegate_followup takes job_id or session_id, plus the same prompt/prompt_file pair and optional permission_mode, max_turns, wait_seconds.

Operating it

Asynchronous by default

delegate_start returns a job_id in milliseconds; the delegate keeps running in the background. This keeps a long task from stalling your session or tripping an MCP client timeout.

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

Pass wait_seconds on any of those to block instead — useful for short tasks where a round trip of polling is not worth it.

Two-way conversations

Every job carries a session_id. Passing its job_id to delegate_followup resumes the session with full history; the session_id stays stable across turns while each turn gets a fresh 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)

Following up is much cheaper than starting fresh when the delegate already has the relevant context loaded.

Long prompts

Every prompt parameter has a prompt_file counterpart. Internally the prompt is always written to disk and fed to the CLI over stdin — never as an argv entry and never through a shell. Backticks, $(...), quotes, newlines and glob characters pass through verbatim, and there is no argv length limit.

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

Permissions

Delegates default to defaultPermissionMode (auto). Narrow a specific call:

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

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

Trusting delegated output

Every finished result reports its tool-call count. Weaker models sometimes answer confidently without running anything — during development, one model claimed an environment variable was unset without ever invoking Bash; when pushed, it ran the command and reported the correct value.

A result carrying tool calls: 0 is therefore annotated as unverified:

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

delegate_status shows the actual trace. A purely conversational follow-up legitimately has zero — the flag means "nothing backs this", not "something broke".

Cancelling

delegate_cancel({ job_id: "A" })

Kills the delegate and everything it started, so a delegate that was midway through a long build does not leave the build running.

Job artifacts

Each job writes to ~/.ollama-mcp/jobs/<job_id>/:

Results longer than maxInlineChars are truncated in the tool response and the full text read from result.txt. Nothing is pruned automatically — delete the directory whenever you like.

Troubleshooting

Cannot reach Ollama at http://127.0.0.1:11434 Ollama is not running. Start ollama serve or open the desktop app. If it listens elsewhere, set OLLAMA_MCP_BASE_URL.

No models available from Ollama ollama pull qwen3.5:397b-cloud, and ollama signin for :cloud models.

<model> was retired at … (HTTP 410) Ollama removed that cloud model. ollama list still shows locally cached manifests for retired models — check what actually works and update defaultModel.

Model "x" is not in the allowed list Working as intended. ollama-mcp-config --allow <models>, then restart.

Tools do not appear in Claude Code The tool list is read at session start. Restart, or check claude mcp list.

Delegate fails instantly with a launch error The CLI was not found. Set OLLAMA_MCP_CLAUDE_BIN to the absolute path of claude.

Everything is slow Cloud models pay a round trip per turn, and Claude Code sends a large system prompt (~25k tokens) on every request. Use max_turns to cap agentic loops and allowed_tools to stop the delegate exploring more than it needs to.

Platform support

Platform differences are isolated in src/platform.ts:

Binary resolution. On POSIX, spawn searches PATH. On Windows a native install gives claude.exe while an npm install gives claude.cmd, which CreateProcess cannot execute directly — so the server walks PATH × PATHEXT preferring .exe, and falls back to routing a .cmd shim through cmd.exe.

Argument escaping. That fallback applies two layers: MSVCRT argv quoting, then a caret escape of cmd's own metacharacters (& | < > ^ " ( ) % !). Skipping the second layer is the classic .cmd command-injection hole. Prompts never touch this path — they travel over stdin. One limitation: a multi-line append_system_prompt cannot cross a cmd.exe command line, so the server raises a clear error pointing at OLLAMA_MCP_CLAUDE_BIN instead of silently mangling it.

Environment allowlist. Windows preserves a much larger set than POSIX. SystemRoot and windir are not optional — strip them and Winsock fails to initialise, so the child cannot open a socket even to localhost. Names are matched case-insensitively but copied with the parent's original spelling.

Cancellation. POSIX children are spawned detached as process-group leaders and cancelled with process.kill(-pid); Windows uses taskkill /T /F. Either way the delegate's own subprocesses die with it. The server also kills running delegates when it shuts down.

Security model

Credential isolation is the point. The child environment is constructed from scratch rather than inherited, and provider variables are stripped before the Ollama values are applied. This is covered by test/env-unit.mjs, and test/e2e.mjs poisons the parent with a fake ANTHROPIC_API_KEY and asserts it never reaches the delegate.

Delegation policy is not model-writable. There is no MCP tool to change delegationMode or allowedModels. An earlier version had one, which was a mistake: a model that finds ondemand inconvenient could flip itself to auto in a single call and then delegate freely. Settings now load once at startup, are never mutated at runtime, and the tool descriptions state that the policy is not the model's to change.

This is a guardrail, not a security boundary. An agent with shell access can still edit the config file. What removing the tool buys you is that such a change is a visible file edit that only takes effect on the next restart, rather than a single silent tool call mid-task. To make it airtight, pin the values via --env on the MCP registration, which overrides the config files:

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

Delegates inherit your filesystem. They run as your user in the cwd you give them, with defaultPermissionMode. Treat a delegated session as you would any Claude Code session — use disallowed_tools or a read-only permission mode when handing work to a model you trust less.

Development

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

Tests

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 runs the three that need no network.

Publishing a release

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

The package is claude-ollama-delegate-mcp and ships only dist/, README.md and LICENSE. publishConfig.access is public, and prepare runs tsc before packing, so a stale dist/ can never be published. Preview the tarball with npm pack --dry-run before shipping.

Layout

License

MIT — see LICENSE.