ollama-mcp

Делегируйте задачи из сессии Claude Code на базе Anthropic сессиям Claude Code на базе Ollama — без того, чтобы они когда-либо обменивались переменными окружения.

ollama launch claude --model <model> работает, экспортируя переменные ANTHROPIC_* в вашу оболочку. Именно поэтому обычно требуется отдельный терминал: переменные действуют на уровне процесса, поэтому одна оболочка — это либо «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>

Все три слота модели указывают на одну и ту же модель 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

Облачные и локальные модели. Модели с тегом :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 — список инструментов считывается при запуске.

Конфигурация

Настройки разрешаются из четырех уровней, причем более поздние переопределяют более ранние:

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 помечает исключенные модели как ЗАБЛОКИРОВАНО 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 и никогда через оболочку. Обратные кавычки, $(...), кавычки, символы новой строки и символы glob передаются дословно, и нет ограничения на длину 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, и ollama signin для моделей :cloud.

<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.

Экранирование аргументов. Этот запасной вариант применяет два слоя: квотирование argv MSVCRT, затем экранирование собственных метасимволов cmd с помощью caret (& | < > ^ " ( ) % !). Пропуск второго слоя — классическая дыра для внедрения команд в .cmd. Промпты никогда не проходят по этому пути — они передаются через stdin. Одно ограничение: многострочный append_system_prompt не может пересекать командную строку cmd.exe, поэтому сервер выдаёт чёткую ошибку, указывающую на OLLAMA_MCP_CLAUDE_BIN, вместо того чтобы молча исказить её.

Белый список окружения. Windows сохраняет гораздо больший набор, чем POSIX. SystemRoot и windir не являются опциональными — удалите их, и Winsock не сможет инициализироваться, поэтому дочерний процесс не сможет открыть сокет даже к localhost. Имена сопоставляются без учёта регистра, но копируются с оригинальным написанием родительского процесса.

Отмена. Дочерние процессы POSIX порождаются detached как лидеры групп процессов и отменяются с помощью process.kill(-pid); Windows использует taskkill /T /F. В любом случае собственные подпроцессы делегата умирают вместе с ним. Сервер также убивает работающих делегатов при завершении работы.

Модель безопасности

Изоляция учётных данных — это суть. Окружение дочернего процесса строится с нуля, а не наследуется, и переменные провайдера удаляются перед применением значений Ollama. Это проверяется в test/env-unit.mjs, а test/e2e.mjs засоряет родительский процесс поддельным ANTHROPIC_API_KEY и утверждает, что он никогда не достигает делегата.

Политика делегирования не доступна для записи модели. Нет инструмента MCP для изменения delegationMode или allowedModels. В более ранней версии такой инструмент был, что было ошибкой: модель, которой неудобен ondemand, могла одним вызовом переключить себя на auto и затем свободно делегировать. Настройки теперь загружаются один раз при запуске, никогда не изменяются во время выполнения, и в описаниях инструментов указано, что политика не подлежит изменению моделью.

Это ограждение, а не граница безопасности. Агент с доступом к оболочке всё равно может редактировать файл конфигурации. Удаление инструмента даёт вам то, что такое изменение будет видимым редактированием файла, которое вступает в силу только при следующем перезапуске, а не одним тихим вызовом инструмента посреди задачи. Чтобы сделать это герметичным, зафиксируйте значения через --env при регистрации MCP, что переопределяет файлы конфигурации:

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 запускает три теста, которые не требуют сети.

Публикация релиза

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/ никогда не может быть опубликован. Просмотрите tarball с помощью npm pack --dry-run перед отправкой.

Структура

Лицензия

MIT — см. LICENSE.