ollama-mcp

Delegar tareas desde una sesión de Claude Code respaldada por Anthropic a sesiones de Claude Code respaldadas por Ollama — sin que las dos compartan nunca variables de entorno.

ollama launch claude --model <model> funciona exportando variables ANTHROPIC_* a tu shell. Por eso normalmente necesita su propio terminal: las variables son a nivel de proceso, por lo que un shell es o bien "Anthropic" o bien "Ollama", nunca ambos.

Este servidor MCP genera cada sesión delegada como un proceso hijo con un entorno explícitamente construido. Tu sesión Opus conserva sus propias credenciales y ajustes de modelo; el delegado recibe los de Ollama. Se ejecutan en paralelo en el mismo 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

Contenido

• Cómo funciona

• Requisitos previos

• Instalación

• Configuración

• Modos de delegación

• Referencia de herramientas

• Operación

• Artefactos de trabajos

• Solución de problemas

• Soporte de plataforma

• Modelo de seguridad

• Desarrollo

Related MCP server: codex-as-mcp

Cómo funciona

El servidor de Ollama expone un endpoint compatible con Anthropic POST /v1/messages, por lo que Claude Code puede comunicarse con él sin modificaciones si se apunta a la URL base correcta. Cada tarea delegada se ejecuta como claude -p en su propio proceso con:

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>

Los tres espacios de modelo apuntan al mismo modelo de Ollama para que los alias (opus, sonnet, haiku) y cualquier subagente generado dentro del delegado se resuelvan a él, en lugar de caer silenciosamente en un valor predeterminado de Anthropic.

El entorno hijo se construye a partir de una pequeña lista de permitidos por plataforma. Cualquier cosa que coincida con ANTHROPIC_*, CLAUDE_*, AWS_*, GOOGLE_*, AZURE_*, OPENAI_*, BEDROCK_*, VERTEX_* se elimina antes de aplicar los valores de Ollama, por lo que una ANTHROPIC_API_KEY suelta en tu shell no puede filtrarse a — ni facturarse en — una ejecución delegada.

Los delegados también se inician con --strict-mcp-config y sin configuración de MCP, lo que mantiene su inicio rápido y evita que llamen recursivamente a este servidor.

Requisitos previos

Verifica las piezas antes de instalar:

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

Modelos cloud vs. locales. Los modelos etiquetados :cloud se ejecutan en la infraestructura de Ollama y requieren ollama signin; son mucho más capaces que lo que la mayoría de portátiles caben en memoria, lo que los convierte en la opción práctica para delegación. Los modelos locales también funcionan y nunca abandonan tu máquina.

Instalación

Desde npm (recomendado)

No se necesita clonar ni compilar — npx lo obtiene bajo demanda:

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

O instálalo globalmente, lo que también pone el CLI de configuración en tu PATH:

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

Desde fuente

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"

Ejecuta el CLI de configuración como node dist/cli.js …, o npm link para tener ollama-mcp-config en tu PATH.

Ámbitos

--scope user lo hace disponible en todos los proyectos; --scope project escribe en .mcp.json en el repositorio actual y lo comparte con colaboradores; --scope local lo mantiene solo para esta máquina y proyecto.

Confirmar

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

Luego reinicia tu sesión de Claude Code — la lista de herramientas se lee al inicio.

Configuración

La configuración se resuelve desde cuatro capas, ganando la última sobre la anterior:

1. valores predeterminados internos

2. configuración de usuario — ~/.ollama-mcp/config.json (sobrescribe la ruta con $OLLAMA_MCP_CONFIG)

3. configuración de proyecto — ./ollama-mcp.config.json en el directorio de trabajo del servidor

4. variables de entorno

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

Cambiar la configuración

La configuración se cambia desde un terminal, nunca por el modelo:

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

Luego reinicia tu sesión de Claude Code para que el servidor relea su configuración.

No hay intencionadamente una herramienta MCP para esto. Ver Modelo de seguridad.

Modelos permitidos

allowedModels: [] (el valor predeterminado) permite cualquier modelo que ofrezca el servidor. Con una lista no vacía:

• delegate_start rechaza un modelo fuera de ella, nombrando el conjunto permitido en lugar de sustituir uno silenciosamente

• ollama_models marca los modelos excluidos como BLOQUEADO por allowedModels

• la lista permitida está incrustada en la descripción de la herramienta delegate_start, para que el orquestador conozca el menú sin una llamada extra

• el CLI rechaza un cambio que dejaría defaultModel fuera de la nueva lista

Modos de delegación

Esto controla con qué entusiasmo el orquestador recurre a la delegación, reescribiendo las descripciones de herramientas que el modelo realmente lee. Cambiarlo requiere reiniciar la sesión, por diseño.

En modo auto la descripción le indica al orquestador que delegue trabajo que sea autocontenido, fácilmente verificable y que consuma mucho contexto — resumen masivo de archivos, búsquedas de primer paso, refactorizaciones mecánicas, código repetitivo y andamios de pruebas, triaje de registros o diffs — mientras que mantiene para sí mismo las decisiones de arquitectura, cambios sensibles a la seguridad, requisitos ambiguos y la revisión final. También se le indica que verifique las afirmaciones delegadas, por la razón en Operación.

Referencia de herramientas

delegate_start

delegate_followup toma job_id o session_id, más el mismo par prompt/prompt_file y permission_mode, max_turns, wait_seconds opcionales.

Operación

Asíncrono por defecto

delegate_start devuelve un job_id en milisegundos; el delegado sigue ejecutándose en segundo plano. Esto evita que una tarea larga detenga tu sesión o provoque un tiempo de espera del cliente 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

Pasa wait_seconds en cualquiera de esos para bloquear en su lugar — útil para tareas cortas donde no vale la pena una ida y vuelta de sondeo.

Conversaciones bidireccionales

Cada trabajo lleva un session_id. Pasar su job_id a delegate_followup reanuda la sesión con el historial completo; el session_id permanece estable entre turnos mientras cada turno obtiene un nuevo 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)

El seguimiento es mucho más barato que empezar de nuevo cuando el delegado ya tiene el contexto relevante cargado.

Prompts largos

Cada parámetro de prompt tiene su contraparte prompt_file. Internamente, el prompt siempre se escribe en disco y se envía a la CLI a través de stdin — nunca como entrada argv ni a través de un shell. Las comillas invertidas, $(...), las comillas, los saltos de línea y los caracteres glob se transmiten literalmente, y no hay límite de longitud de argv.

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

Permisos

Los delegados usan por defecto defaultPermissionMode (auto). Restringe una llamada específica:

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

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

Confiar en la salida delegada

Cada resultado finalizado informa su recuento de llamadas a herramientas. Los modelos más débiles a veces responden con confianza sin ejecutar nada — durante el desarrollo, un modelo afirmó que una variable de entorno no estaba configurada sin invocar Bash; al ser presionado, ejecutó el comando e informó el valor correcto.

Un resultado con tool calls: 0 se anota, por tanto, como no verificado:

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

delegate_status muestra el rastro real. Una respuesta puramente conversacional legítimamente tiene cero — la marca significa "esto no está respaldado por nada", no "algo se rompió".

Cancelación

delegate_cancel({ job_id: "A" })

Mata al delegado y todo lo que inició, por lo que un delegado que estuviera a medio camino de una compilación larga no deja la compilación ejecutándose.

Artefactos de trabajo

Cada trabajo escribe en ~/.ollama-mcp/jobs/<job_id>/:

Los resultados más largos que maxInlineChars se truncan en la respuesta de la herramienta y el texto completo se lee de result.txt. No se elimina nada automáticamente — elimina el directorio cuando quieras.

Solución de problemas

Cannot reach Ollama at http://127.0.0.1:11434 Ollama no se está ejecutando. Inicia ollama serve o abre la aplicación de escritorio. Si escucha en otro lugar, establece OLLAMA_MCP_BASE_URL.

No models available from Ollama ollama pull qwen3.5:397b-cloud, y ollama signin para modelos :cloud.

<model> was retired at … (HTTP 410) Ollama eliminó ese modelo en la nube. ollama list aún muestra manifiestos almacenados en caché localmente para modelos retirados — comprueba qué funciona realmente y actualiza defaultModel.

Model "x" is not in the allowed list Funciona según lo previsto. ollama-mcp-config --allow <models>, luego reinicia.

Las herramientas no aparecen en Claude Code La lista de herramientas se lee al inicio de la sesión. Reinicia, o comprueba claude mcp list.

El delegado falla instantáneamente con un error de inicio No se encontró la CLI. Establece OLLAMA_MCP_CLAUDE_BIN en la ruta absoluta de claude.

Todo es lento Los modelos en la nube pagan un viaje de ida y vuelta por turno, y Claude Code envía un prompt de sistema grande (~25k tokens) en cada solicitud. Usa max_turns para limitar los bucles agentivos y allowed_tools para evitar que el delegado explore más de lo necesario.

Soporte de plataforma

Las diferencias de plataforma están aisladas en src/platform.ts:

Resolución binaria. En POSIX, spawn busca en PATH. En Windows, una instalación nativa da claude.exe mientras que una instalación npm da claude.cmd, que CreateProcess no puede ejecutar directamente — por lo que el servidor recorre PATH × PATHEXT prefiriendo .exe, y recurre a enrutar un shim .cmd a través de cmd.exe.

Escapado de argumentos. Esa alternativa aplica dos capas: el citado argv de MSVCRT, luego un escapado con caret de los propios metacaracteres de cmd (& | < > ^ " ( ) % !). Omitir la segunda capa es el clásico agujero de inyección de comandos .cmd. Los prompts nunca tocan esta ruta — viajan por stdin. Una limitación: un append_system_prompt de múltiples líneas no puede cruzar una línea de comandos de cmd.exe, por lo que el servidor genera un error claro señalando OLLAMA_MCP_CLAUDE_BIN en lugar de mutilarlo silenciosamente.

Lista blanca de entorno. Windows conserva un conjunto mucho más grande que POSIX. SystemRoot y windir no son opcionales — elimínalos y Winsock falla al inicializarse, por lo que el hijo no puede abrir un socket ni siquiera para localhost. Los nombres se comparan sin distinción de mayúsculas y minúsculas, pero se copian con la ortografía original del padre.

Cancelación. Los hijos de POSIX se generan detached como líderes de grupo de procesos y se cancelan con process.kill(-pid); Windows usa taskkill /T /F. De cualquier manera, los propios subprocesos del delegado mueren con él. El servidor también mata a los delegados en ejecución cuando se apaga.

Modelo de seguridad

El aislamiento de credenciales es el punto. El entorno hijo se construye desde cero en lugar de heredarse, y las variables del proveedor se eliminan antes de aplicar los valores de Ollama. Esto está cubierto por test/env-unit.mjs, y test/e2e.mjs envenena al padre con una ANTHROPIC_API_KEY falsa y afirma que nunca llega al delegado.

La política de delegación no puede ser escrita por el modelo. No hay ninguna herramienta MCP para cambiar delegationMode o allowedModels. Una versión anterior tenía una, que fue un error: un modelo que encuentra inconveniente ondemand podría cambiarse a auto en una sola llamada y luego delegar libremente. La configuración ahora se carga una vez al inicio, nunca se muta en tiempo de ejecución, y las descripciones de las herramientas indican que la política no puede ser cambiada por el modelo.

Esto es una barrera de protección, no un límite de seguridad. Un agente con acceso al shell aún puede editar el archivo de configuración. Lo que te compra eliminar la herramienta es que tal cambio es una edición de archivo visible que solo surte efecto en el próximo reinicio, en lugar de una única llamada silenciosa a la herramienta en medio de una tarea. Para hacerlo hermético, fija los valores a través de --env en el registro MCP, que anula los archivos de configuración:

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

Los delegados heredan tu sistema de archivos. Se ejecutan como tu usuario en el cwd que les des, con defaultPermissionMode. Trata una sesión delegada como lo harías con cualquier sesión de Claude Code — usa disallowed_tools o un modo de permiso de solo lectura al asignar trabajo a un modelo en el que confíes menos.

Desarrollo

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

Pruebas

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 ejecuta las tres que no necesitan red.

Publicar un lanzamiento

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

El paquete es claude-ollama-delegate-mcp y envía solo dist/, README.md y LICENSE. publishConfig.access es public, y prepare ejecuta tsc antes de empaquetar, por lo que nunca se puede publicar un dist/ obsoleto. Previsualiza el tarball con npm pack --dry-run antes de enviar.

Diseño

Licencia

MIT — consulta LICENSE.