ollama-mcp

Delegieren Sie Aufgaben von einer Anthropic-unterstützten Claude Code-Sitzung an Ollama-unterstützte Claude Code-Sitzungen – ohne dass die beiden jemals Umgebungsvariablen teilen.

ollama launch claude --model <model> funktioniert, indem es ANTHROPIC_*-Variablen in Ihre Shell exportiert. Deshalb benötigt es normalerweise ein eigenes Terminal: Die Variablen sind prozessweit, daher ist eine Shell entweder „Anthropic“ oder „Ollama“, niemals beide.

Dieser MCP-Server startet jede delegierte Sitzung als Kindprozess mit einer explizit konstruierten Umgebung. Ihre Opus-Sitzung behält ihre eigenen Anmeldeinformationen und Modelleinstellungen; der Delegat erhält die von Ollama. Sie laufen nebeneinander im selben 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

Inhaltsverzeichnis

• Wie es funktioniert

• Voraussetzungen

• Installation

• Konfiguration

• Delegationsmodi

• Werkzeugreferenz

• Bedienung

• Job-Artefakte

• Fehlerbehebung

• Plattformunterstützung

• Sicherheitsmodell

• Entwicklung

Related MCP server: codex-as-mcp

Wie es funktioniert

Der Server von Ollama stellt einen Anthropic-kompatiblen POST /v1/messages-Endpunkt bereit, sodass Claude Code unverändert damit kommunizieren kann, wenn es auf die richtige Basis-URL ausgerichtet ist. Jede delegierte Aufgabe wird als claude -p in einem eigenen Prozess ausgeführt mit:

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>

Alle drei Modellplätze zeigen auf dasselbe Ollama-Modell, sodass Aliase (opus, sonnet, haiku) und alle innerhalb des Delegaten erzeugten Subagenten darauf aufgelöst werden, anstatt stillschweigend auf einen Anthropic-Standard zurückzufallen.

Die Kind-Umgebung wird aus einer kleinen, plattformspezifischen Whitelist aufgebaut. Alles, was auf ANTHROPIC_*, CLAUDE_*, AWS_*, GOOGLE_*, AZURE_*, OPENAI_*, BEDROCK_*, VERTEX_* passt, wird vor dem Anwenden der Ollama-Werte entfernt, sodass ein versehentlicher ANTHROPIC_API_KEY in Ihrer Shell nicht in einen delegierten Lauf durchsickern oder ihn belasten kann.

Delegaten starten auch mit --strict-mcp-config und ohne MCP-Konfiguration, was ihren Start beschleunigt und verhindert, dass sie rekursiv diesen Server aufrufen.

Voraussetzungen

Überprüfen Sie die Komponenten vor der Installation:

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. lokale Modelle. Modelle mit dem Tag :cloud laufen auf der Infrastruktur von Ollama und erfordern ollama signin; sie sind weitaus leistungsfähiger als das, was die meisten Laptops in den Arbeitsspeicher fassen, was sie zur praktischen Wahl für die Delegation macht. Lokale Modelle funktionieren ebenfalls und verlassen niemals Ihren Rechner.

Installation

Von npm (empfohlen)

Kein Klonen oder Bauen erforderlich – npx holt es bei Bedarf:

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

Oder installieren Sie es global, was auch das Einstellungs-CLI in Ihren PATH bringt:

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

Aus dem Quellcode

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"

Führen Sie das Einstellungs-CLI als node dist/cli.js … aus, oder npm link, um ollama-mcp-config in Ihren PATH zu bekommen.

Bereiche

--scope user macht es in jedem Projekt verfügbar; --scope project schreibt in .mcp.json im aktuellen Repository und teilt es mit Mitarbeitern; --scope local behält es auf diesem Rechner und Projekt.

Bestätigung

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

Dann starten Sie Ihre Claude Code-Sitzung neu – die Werkzeugliste wird beim Start gelesen.

Konfiguration

Einstellungen werden aus vier Ebenen aufgelöst, wobei die spätere die frühere überschreibt:

1. integrierte Standardwerte

2. Benutzerkonfiguration – ~/.ollama-mcp/config.json (Pfad überschreiben mit $OLLAMA_MCP_CONFIG)

3. Projektkonfiguration – ./ollama-mcp.config.json im Arbeitsverzeichnis des Servers

4. Umgebungsvariablen

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

Einstellungen ändern

Einstellungen werden von einem Terminal aus geändert, niemals durch das Modell:

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

Dann starten Sie Ihre Claude Code-Sitzung neu, damit der Server seine Konfiguration neu einliest.

Es gibt bewusst kein MCP-Werkzeug dafür. Siehe Sicherheitsmodell.

Erlaubte Modelle

allowedModels: [] (der Standard) erlaubt jedes Modell, das der Server anbietet. Mit einer nicht leeren Liste:

• delegate_start lehnt ein Modell außerhalb der Liste ab, wobei die erlaubte Menge genannt wird, anstatt stillschweigend ein anderes zu ersetzen

• ollama_models markiert ausgeschlossene Modelle als BLOCKED by allowedModels

• die erlaubte Liste ist in die Beschreibung des Werkzeugs delegate_start eingebettet, sodass der Orchestrator das Menü ohne zusätzlichen Aufruf kennt

• das CLI lehnt eine Änderung ab, die defaultModel außerhalb der neuen Liste belassen würde

Delegationsmodi

Dies steuert, wie eifrig der Orchestrator zur Delegation greift, indem die Werkzeugbeschreibungen umgeschrieben werden, die das Modell tatsächlich liest. Eine Änderung erfordert einen Sitzungsneustart, wie beabsichtigt.

Im Modus auto wird dem Orchestrator in der Beschreibung mitgeteilt, dass er Arbeiten delegieren soll, die in sich abgeschlossen, kostengünstig verifizierbar und kontexthungrig sind – Bulk-Dateizusammenfassungen, erste Durchsuchen, mechanische Refactorings, Boilerplate- und Testgerüste, Log- oder Diff-Triage – während Architekturentscheidungen, sicherheitskritische Änderungen, mehrdeutige Anforderungen und die endgültige Überprüfung für sich selbst behalten werden. Er wird auch angewiesen, delegierte Behauptungen zu überprüfen, aus dem Grund in Bedienung.

Werkzeugreferenz

delegate_start

delegate_followup akzeptiert job_id oder session_id, plus dasselbe Paar aus prompt/prompt_file und optionalem permission_mode, max_turns, wait_seconds.

Bedienung

Standardmäßig asynchron

delegate_start gibt eine job_id in Millisekunden zurück; der Delegat läuft im Hintergrund weiter. Dadurch wird verhindert, dass eine lange Aufgabe Ihre Sitzung blockiert oder einen MCP-Client-Timeout auslöst.

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

Übergeben Sie wait_seconds bei einem dieser Aufrufe, um stattdessen zu blockieren – nützlich für kurze Aufgaben, bei denen ein Roundtrip des Abfragens nicht lohnt.

Zwei-Wege-Gespräche

Jeder Job trägt eine session_id. Die Übergabe seiner job_id an delegate_followup setzt die Sitzung mit vollständigem Verlauf fort; die session_id bleibt über Züge hinweg stabil, während jeder Zug eine neue job_id erhält.

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)

Das Nachfassen ist viel billiger als ein Neustart, wenn der Delegat den relevanten Kontext bereits geladen hat.

Lange Eingabeaufforderungen

Jeder Prompt-Parameter hat ein prompt_file-Gegenstück. Intern wird der Prompt immer auf die Festplatte geschrieben und dem CLI über stdin zugeführt — niemals als argv-Eintrag und niemals durch eine Shell. Backticks, $(...), Anführungszeichen, Zeilenumbrüche und Glob-Zeichen werden unverändert durchgereicht, und es gibt keine argv-Längenbeschränkung.

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

Berechtigungen

Delegates verwenden standardmäßig defaultPermissionMode (auto). Schränken Sie einen bestimmten Aufruf ein:

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

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

Vertrauen in delegierte Ausgabe

Jedes abgeschlossene Ergebnis meldet seine Tool-Call-Anzahl. Schwächere Modelle antworten manchmal mit Überzeugung, ohne etwas auszuführen — während der Entwicklung behauptete ein Modell, eine Umgebungsvariable sei nicht gesetzt, ohne jemals Bash aufzurufen; nach einer Aufforderung führte es den Befehl aus und meldete den korrekten Wert.

Ein Ergebnis mit tool calls: 0 wird daher als unverifiziert gekennzeichnet:

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

delegate_status zeigt den tatsächlichen Ablauf. Eine rein konversationelle Nachfrage hat legitim null — das Flag bedeutet „nichts untermauert dies“, nicht „etwas ist kaputt“.

Abbrechen

delegate_cancel({ job_id: "A" })

Beendet den Delegate und alles, was er gestartet hat, sodass ein Delegate, der mitten in einem langen Build steckt, den Build nicht weiterlaufen lässt.

Job-Artefakte

Jeder Job schreibt nach ~/.ollama-mcp/jobs/<job_id>/:

Ergebnisse, die länger als maxInlineChars sind, werden in der Tool-Antwort gekürzt, und der vollständige Text wird aus result.txt gelesen. Es wird nichts automatisch gelöscht — löschen Sie das Verzeichnis, wann immer Sie möchten.

Fehlerbehebung

Cannot reach Ollama at http://127.0.0.1:11434 Ollama läuft nicht. Starten Sie ollama serve oder öffnen Sie die Desktop-App. Wenn es an einem anderen Ort horcht, setzen Sie OLLAMA_MCP_BASE_URL.

No models available from Ollama ollama pull qwen3.5:397b-cloud und ollama signin für :cloud-Modelle.

<model> was retired at … (HTTP 410) Ollama hat dieses Cloud-Modell entfernt. ollama list zeigt weiterhin lokal zwischengespeicherte Manifeste für entfernte Modelle an — prüfen Sie, was tatsächlich funktioniert, und aktualisieren Sie defaultModel.

Model "x" is not in the allowed list Funktioniert wie vorgesehen. ollama-mcp-config --allow <models>, dann neu starten.

Tools erscheinen nicht in Claude Code Die Tool-Liste wird beim Start der Sitzung gelesen. Starten Sie neu oder prüfen Sie mit claude mcp list.

Delegate schlägt sofort mit einem Startfehler fehl Das CLI wurde nicht gefunden. Setzen Sie OLLAMA_MCP_CLAUDE_BIN auf den absoluten Pfad von claude.

Alles ist langsam Cloud-Modelle zahlen einen Roundtrip pro Zug, und Claude Code sendet bei jeder Anfrage einen großen System-Prompt (~25k Token). Verwenden Sie max_turns, um agentische Schleifen zu begrenzen, und allowed_tools, um den Delegate daran zu hindern, mehr zu erkunden, als nötig.

Plattformunterstützung

Plattformunterschiede sind in src/platform.ts isoliert:

Binärauflösung. Unter POSIX durchsucht spawn den PATH. Unter Windows liefert eine native Installation claude.exe, während eine npm-Installation claude.cmd liefert, das CreateProcess nicht direkt ausführen kann — daher durchläuft der Server PATH × PATHEXT, bevorzugt .exe, und fällt darauf zurück, einen .cmd-Shim durch cmd.exe zu leiten.

Argument-Escaping. Dieser Fallback wendet zwei Ebenen an: MSVCRT-argv-Zitierung, dann ein Caret-Escaping von cmd's eigenen Metazeichen (& | < > ^ " ( ) % !). Das Überspringen der zweiten Ebene ist das klassische .cmd-Befehlsinjektionsloch. Prompts berühren diesen Pfad nie — sie reisen über stdin. Eine Einschränkung: Ein mehrzeiliges append_system_prompt kann keine cmd.exe-Befehlszeile überqueren, daher gibt der Server einen klaren Fehler aus, der auf OLLAMA_MCP_CLAUDE_BIN verweist, anstatt es stillschweigend zu verstümmeln.

Umgebungs-Allowlist. Windows bewahrt eine viel größere Menge als POSIX. SystemRoot und windir sind nicht optional — entfernt man sie, schlägt Winsock fehl zu initialisieren, sodass das Kind keinen Socket öffnen kann, nicht einmal zu localhost. Namen werden case-insensitiv abgeglichen, aber mit der ursprünglichen Schreibweise des Elternteils kopiert.

Abbruch. POSIX-Kinder werden detached als Prozessgruppenführer erzeugt und mit process.kill(-pid) abgebrochen; Windows verwendet taskkill /T /F. In beiden Fällen sterben die eigenen Unterprozesse des Delegaten mit ihm. Der Server beendet auch laufende Delegaten, wenn er heruntergefahren wird.

Sicherheitsmodell

Credential-Isolation ist der Punkt. Die Kind-Umgebung wird von Grund auf neu erstellt und nicht vererbt, und Anbieter-Variablen werden entfernt, bevor die Ollama-Werte angewendet werden. Dies wird durch test/env-unit.mjs abgedeckt, und test/e2e.mjs vergiftet das Elternteil mit einem gefälschten ANTHROPIC_API_KEY und stellt sicher, dass es den Delegate nie erreicht.

Delegierungsrichtlinie ist nicht modell-schreibbar. Es gibt kein MCP-Tool, um delegationMode oder allowedModels zu ändern. Eine frühere Version hatte eines, was ein Fehler war: Ein Modell, das ondemand unpraktisch findet, könnte sich selbst in einem einzigen Aufruf auf auto umstellen und dann frei delegieren. Einstellungen werden jetzt einmal beim Start geladen, werden zur Laufzeit nie verändert, und die Tool-Beschreibungen geben an, dass die Richtlinie nicht vom Modell geändert werden darf.

Dies ist eine Leitplanke, keine Sicherheitsgrenze. Ein Agent mit Shell-Zugriff kann die Konfigurationsdatei immer noch bearbeiten. Was Ihnen das Entfernen des Tools bringt, ist, dass eine solche Änderung eine sichtbare Dateibearbeitung ist, die erst beim nächsten Neustart wirksam wird, und nicht ein einzelner stiller Tool-Call mitten in der Aufgabe. Um es wasserdicht zu machen, fixieren Sie die Werte über --env bei der MCP-Registrierung, was die Konfigurationsdateien überschreibt:

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 erben Ihr Dateisystem. Sie laufen als Ihr Benutzer in dem cwd, das Sie ihnen geben, mit defaultPermissionMode. Behandeln Sie eine delegierte Sitzung wie jede andere Claude Code-Sitzung — verwenden Sie disallowed_tools oder einen schreibgeschützten Berechtigungsmodus, wenn Sie einem Modell, dem Sie weniger vertrauen, Arbeit übergeben.

Entwicklung

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 führt die drei aus, die kein Netzwerk benötigen.

Eine Version veröffentlichen

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

Das Paket heißt claude-ollama-delegate-mcp und liefert nur dist/, README.md und LICENSE aus. publishConfig.access ist public, und prepare führt tsc vor dem Packen aus, sodass ein veraltetes dist/ nie veröffentlicht werden kann. Zeigen Sie das Tarball mit npm pack --dry-run vor dem Versand an.

Aufbau

Lizenz

MIT — siehe LICENSE.