MCP Client for Ollama

Un cliente en Python que conecta LLMs locales a través de Ollama con servidores del Protocolo de Contexto de Modelo, permitiéndoles usar herramientas.

GitHub

826

Prueba este MCPPatrocinado

Documentación

Un cliente de Python simple pero potente para interactuar con servidores del Protocolo de Contexto de Modelos (MCP) usando Ollama, que te permite aprovechar LLMs locales para la ejecución avanzada de herramientas.

English | 简体中文 | Español

MCP Client for Ollama (ollmcp)

Pepy Total Downloads

_{Patrocinado por}

_{Aprende cómo usar Atlas Cloud con ollmcp en la sección de Patrocinadores}

MCP Client for Ollama Demo

🎥 Mira esta demo como una grabación de Asciinema

Tabla de Contenidos

Descripción General
Características
Requisitos
Inicio Rápido
Opciones de Instalación
Solución de Problemas
✨NUEVO Gestión de Servidores MCP mediante CLI
Comandos Interactivos
Funciones de Autocompletado y Prompts
Gestión de Configuración
- ✨NUEVO Perfiles por proveedor
Formato de Configuración del Servidor
- Consejos: Dónde Colocar las Configuraciones de Servidores MCP y un Ejemplo Funcional
Modelos Compatibles
- Modelos de Ollama Cloud
✨NUEVO Patrocinadores
- Atlas Cloud
- Conviértete en patrocinador
¿Dónde Puedo Encontrar Más Servidores MCP?
Proyectos Relacionados
Seguridad
Licencia
Agradecimientos

Descripción General

MCP Client for Ollama (ollmcp) es una aplicación de terminal interactiva moderna (TUI) construida para ingeniería de harness, que conecta LLMs locales de Ollama a uno o más servidores del Protocolo de Contexto de Modelos (MCP). Al admitir completamente los primitivos centrales de MCP (herramientas, prompts y recursos), proporciona un espacio de terminal controlado donde tú diriges y el agente ejecuta. Con una interfaz rica y fácil de usar, te permite gestionar tu configuración de forma segura en tiempo real sin necesidad de programar. Ya sea que estés construyendo, probando o explorando, este cliente optimiza tu flujo de trabajo con funciones como autocompletado difuso, configuración avanzada de modelos, recarga en caliente de servidores MCP para desarrollo rápido y controles estrictos de seguridad con Supervisión Humana.

Características

🤖 Modo Agente: Ejecución iterativa de herramientas cuando los modelos solicitan múltiples llamadas a herramientas, con un límite de bucle configurable y opciones interactivas cuando se alcanza el límite (continuar, finalizar o abortar)
🌐 Soporte Multi-Servidor: Conéctate a múltiples servidores MCP simultáneamente
🚀 Múltiples Tipos de Transporte: Admite conexiones a servidores STDIO, SSE y HTTP Streamable
📋 Soporte de Prompts MCP: Explora, invoca y gestiona prompts de servidores MCP con recopilación de argumentos, vista previa y reversión segura
📦 Soporte de Recursos MCP: Explora y lee datos contextuales de servidores MCP, incluidos archivos, documentos y datos estructurados
☁️ Soporte de Ollama Cloud: Funciona perfectamente con modelos de Ollama Cloud para llamadas a herramientas, lo que permite acceder a potentes modelos alojados en la nube mientras usas herramientas MCP locales
🌍 Múltiples Proveedores de LLM: Usa Ollama (predeterminado) o proveedores compatibles con OpenAI (OpenAI, OpenRouter, DeepSeek, etc.), con configuraciones de conexión recordadas por proveedor
🎨 Interfaz de Terminal Enriquecida: Interfaz de consola interactiva con estilo moderno
🌊 Respuestas en Streaming: Ve las salidas del modelo en tiempo real mientras se generan
📝 Modos de Visualización de Respuestas: Cambia entre vistas de respuesta Plano, Markdown, Ambos o Markdown (bloques) durante el streaming
🛠️ Gestión de Herramientas: Habilita/deshabilita herramientas específicas o servidores completos durante las sesiones de chat
🧑‍💻 Supervisión Humana (HIL): Revisa y aprueba las ejecuciones de herramientas antes de que se ejecuten para mayor control y seguridad
🎮 Configuración Avanzada del Modelo: Ajusta más de 15 parámetros del modelo, incluidos el tamaño de la ventana de contexto, temperatura, muestreo, control de repetición y más
💬 Personalización del Prompt del Sistema: Define y edita el prompt del sistema para controlar el comportamiento y la personalidad del modelo
🧠 Control de la Ventana de Contexto: Ajusta el tamaño de la ventana de contexto (num_ctx) para manejar conversaciones más largas y tareas complejas
🎨 Visualización Mejorada de Herramientas: Visualización hermosa y estructurada de las ejecuciones de herramientas con resaltado de sintaxis JSON
🧠 Gestión del Contexto: Controla la memoria de la conversación con configuraciones de retención ajustables
🤔 Modo de Pensamiento: Capacidades de razonamiento avanzado con procesos de pensamiento visibles para modelos compatibles (por ejemplo, gpt-oss, deepseek-r1, qwen3, etc.)
💪 Niveles de Esfuerzo de Razonamiento: Establece el esfuerzo de razonamiento en automático, mínimo, bajo, medio, alto o muy alto para modelos compatibles
🖼️ Soporte de Herramientas de Visión: Las imágenes devueltas por las herramientas se reenvían automáticamente a modelos con capacidad de visión
🗣️ Soporte Multilingüe: Trabaja sin problemas con servidores MCP tanto de Python como de JavaScript
📜 Gestión del Historial: Ve el historial completo de la conversación, exporta a JSON para respaldo/análisis e importa sesiones anteriores para continuidad
🔍 Auto-Detección: Encuentra y usa automáticamente las configuraciones de servidores MCP existentes de Claude
🔁 Cambio Dinámico de Modelo: Cambia entre cualquier modelo de Ollama instalado sin reiniciar
💾 Persistencia de Configuración: Guarda y carga preferencias de herramientas y configuraciones de modelo entre sesiones
🔄 Recarga de Servidores: Recarga en caliente los servidores MCP durante el desarrollo sin reiniciar el cliente
✨ Autocompletado Difuso: Autocompletado interactivo de comandos con teclas de flecha y descripciones
🏷️ Prompt Dinámico: Muestra el modelo actual, el modo de pensamiento y las herramientas habilitadas
📊 Métricas de Rendimiento: Datos detallados del rendimiento del modelo después de cada consulta, incluidos tiempos de duración y recuentos de tokens
🔌 Plug-and-Play: Funciona inmediatamente con servidores de herramientas estándar compatibles con MCP
🔔 Notificaciones de Actualización: Detecta automáticamente cuando hay una nueva versión disponible
🖥️ CLI Moderno con Typer: Opciones agrupadas, autocompletado de shell y salida de ayuda mejorada
⏹️ Abortar Generación: Puedes abortar la generación del modelo en cualquier momento presionando 'a' durante el streaming de la respuesta

Requisitos

Python 3.11+ (Guía de instalación)
Ollama ejecutándose localmente (Guía de instalación)
- Después de la instalación, ejecuta ollama list para ver los modelos disponibles. Si no hay modelos instalados, puedes descargar uno usando ollama pull <model_name>. Por ejemplo, ollama pull gemma4:latest.
Gestor de paquetes UV (Guía de instalación)

Inicio Rápido

Instala ollmcp mediante pip, añade un servidor MCP y ejecuta el cliente:

# Install ollmcp via uv
uv tool install --upgrade ollmcp
# or via pip
pip install --upgrade ollmcp
# Add an MCP server (example: playwright stdio server)
ollmcp mcp add playwright -- npx @playwright/mcp@latest
# Run the client (check optional flags with `ollmcp --help`)
ollmcp # once running, use /help for interactive commands

Opciones de Instalación

Opción 1: Instala con uv y ejecuta (recomendado)

uv tool install --upgrade ollmcp
ollmcp

Opción 2: Instala con pip y ejecuta

pip install --upgrade ollmcp
ollmcp

Opción 3: Solo ejecutar sin instalar (requiere el gestor de paquetes uv)

uvx ollmcp

Opción 4: Instala desde el código fuente y ejecuta usando un entorno virtual

git clone https://github.com/jonigl/mcp-client-for-ollama.git
cd mcp-client-for-ollama
uv run -m mcp_client_for_ollama

Solución de Problemas

`Could not find a version that satisfies the requirement ollmcp (from versions: none)`

Esto casi siempre significa que el Python que estás usando es más antiguo que el 3.11+ requerido. Esto es común en macOS, donde el Python del sistema (/usr/bin/python3) o el Python incluido con Xcode pueden ser 3.9 o más antiguos. Cuando ninguna versión coincide con requires-python >= 3.11, pip filtra todas las versiones y reporta el engañoso "from versions: none".

Primero verifica tu versión:

python3 --version   # must be 3.11 or newer

Luego instala con un Python moderno. La opción más simple es uv, que obtiene un Python adecuado automáticamente:

uv tool install --upgrade ollmcp   # recommended, installs the CLI in an isolated environment
# or, if you prefer pip, make sure to use a Python 3.11+ interpreter:
python3.11 -m pip install --upgrade ollmcp
# Then run the client:
ollmcp

Echa un vistazo a las Opciones de Instalación.

`error: externally-managed-environment` (PEP 668)

En Debian/Ubuntu recientes (Python 3.12+), el pip del sistema está bloqueado intencionalmente para proteger los paquetes gestionados por el sistema operativo, por lo que pip install ollmcp está bloqueado. Esta es una política del sistema (PEP 668), no un problema de ollmcp. Instálalo en un entorno aislado en su lugar:

uv tool install --upgrade ollmcp   # recommended, installs the CLI in an isolated environment
# or, if you prefer pip, use a virtual environment:
python3.11 -m venv ollmcp-env
source ollmcp-env/bin/activate
python3.11 -m pip install --upgrade ollmcp
# Then run the client:
ollmcp

Echa un vistazo a las Opciones de Instalación.

[!WARNING] Evita pip install --break-system-packages ollmcp. Funciona, pero instala en el Python del sistema y puede romper paquetes de los que depende tu sistema operativo.

Gestión de Servidores MCP mediante CLI

ollmcp puede gestionar sus propias configuraciones de servidores MCP directamente desde la línea de comandos, similar a claude mcp:

# Remote servers (Streamable HTTP or SSE)
ollmcp mcp add --transport http <name> <url>
ollmcp mcp add --transport sse <name> <url>

# Local stdio servers - everything after `--` is the command to run
ollmcp mcp add [options] <name> -- <command> [args...]

# List configured servers
ollmcp mcp list

# Remove a server
ollmcp mcp remove <name>

# For more details on options and usage, run:
ollmcp mcp --help
ollmcp mcp add --help

Ejemplos:

[!TIP] Una vez que hayas añadido algunos servidores, simplemente ejecutar ollmcp se conectará a ellos automáticamente.

ollmcp mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer $YOUR_GITHUB_PAT"
ollmcp mcp add --transport stdio playwright npx @playwright/mcp@latest
ollmcp mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /allowed-dir1 ~/allowed-dir2 # stdio transport by default
ollmcp mcp add --env API_KEY=YOUR_KEY --transport sse my-sse-server http://localhost:8000/sse

Opciones de mcp add

--transport, -t: stdio (predeterminado), sse o http.
--header, -H: Cabecera HTTP como "Name: Value" para servidores sse/http. Repetible.
--env, -e: Variable de entorno como KEY=value para servidores stdio. Repetible.
--scope, -s: Dónde almacenar el servidor (ver ámbitos a continuación). Predeterminado: local.

Ámbitos

Ámbito	Se carga en	Compartido con el equipo	Almacenado en
`local`	Solo proyecto actual	No	`~/.config/ollmcp/mcp.local.json` (clave por ruta de proyecto)
`project`	Solo proyecto actual	Sí (mediante VCS)	`.mcp.json` en la raíz del proyecto
`user`	Todos tus proyectos	No	`~/.config/ollmcp/mcp.json`

El ámbito project escribe un archivo estándar .mcp.json en la raíz de tu proyecto, compatible con Claude Code y otras herramientas compatibles con MCP. Si el mismo nombre de servidor existe en múltiples ámbitos, la precedencia es local > project > user.

[!NOTE] Los servidores añadidos mediante ollmcp mcp add siempre se cargan como capa base. Cualquier bandera (--mcp-server, --mcp-server-url, --servers-json, --claude-desktop) se añade encima. Para incluir servidores de Claude Desktop, pase --claude-desktop explícitamente.

Si un servidor con el mismo nombre también se proporciona mediante una de esas banderas, ambas conexiones se abren actualmente, pero solo una se mantiene activa bajo ese nombre. Evite reutilizar el nombre de un servidor del registro en --mcp-server/--mcp-server-url/--servers-json/--claude-desktop.

Argumentos de línea de comandos

[!TIP] La CLI ahora usa Typer para una experiencia moderna: opciones agrupadas, ayuda enriquecida y autocompletado de shell integrado. Los usuarios avanzados pueden usar banderas cortas para comandos más rápidos. Para habilitar el autocompletado, ejecute:
ollmcp --install-completion
Luego reinicie su shell o siga las instrucciones impresas.

Configuración del servidor MCP:

--mcp-server, -s: Ruta a uno o más scripts de servidor MCP (.py o .js). Se puede especificar varias veces.
--mcp-server-url, -u: URL a uno o más servidores MCP SSE o Streamable HTTP. Se puede especificar varias veces. Consulte Rutas de endpoint MCP comunes para endpoints típicos.
--servers-json, -j: Ruta a un archivo JSON con configuraciones de servidor. Consulte Formato de configuración de servidor para más detalles.
--claude-desktop: Cargar servidores desde el archivo de configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json). Se combina con servidores añadidos mediante ollmcp mcp add y cualquier otra bandera.

[!IMPORTANT] Cambio importante: --auto-discovery / -a ha sido reemplazado por --claude-desktop. Además, los servidores añadidos mediante ollmcp mcp add ahora siempre se cargan automáticamente, ya no son un respaldo que desaparece cuando se usan otras banderas. Los servidores de Claude Desktop nunca se cargan automáticamente; use --claude-desktop para incluirlos.

Configuración del proveedor de inferencia:

--model, -m MODEL: Modelo a usar. Predeterminado: el modelo de su configuración guardada si está establecido; de lo contrario, el primer modelo disponible en Ollama
--provider, -p PROVIDER: Proveedor de LLM a usar (p. ej. ollama, openai, atlascloud, openrouter, deepseek). Predeterminado: ollama
--host, -H HOST: Host del LLM / URL base de la API. Se establece por defecto en http://localhost:11434 de Ollama para el proveedor ollama, o en el endpoint predeterminado del propio proveedor en caso contrario.
--api-key, -k KEY: Clave API para el proveedor de LLM. También se lee de la variable de entorno $OLLMCP_API_KEY, que es agnóstica al proveedor (se aplica a cualquier proveedor que seleccione con --provider). Las claves pasadas mediante $OLLMCP_API_KEY nunca se escriben en el archivo de configuración; solo se guardan las claves pasadas con --api-key. No es necesario para ollama.

[!NOTE] Proveedores actualmente compatibles: ollama, openai, atlascloud y cualquier proveedor compatible con OpenAI (openrouter, deepseek, perplexity, etc.). Pronto habrá más proveedores.

Opciones generales:

--version, -v: Mostrar versión y salir
--help, -h: Mostrar mensaje de ayuda y salir
--install-completion: Instalar scripts de autocompletado de shell para el cliente
--show-completion: Mostrar opciones de autocompletado de shell disponibles

Registro del servidor MCP:

Todo lo que un servidor MCP reporta se escribe en ~/.config/ollmcp/logs/<session>/<server>.log, un directorio por ejecución, conservando los últimos 5. Nada de lo que un servidor imprime llega a la pantalla a menos que lo solicite — de lo contrario, se dibujaría sobre la respuesta que se está transmitiendo.

Los servidores reportan a través de dos canales: su stderr (solo servidores stdio, ya que uno remoto se ejecuta en otro lugar) y notificaciones de registro MCP (cualquier servidor). Ambas banderas solo cambian lo que ve en pantalla — el archivo de registro recibe todo de cualquier manera:

	escrito en el archivo de registro	mostrado en pantalla
(sin bandera)	todo lo que el servidor envía	nada del servidor
`--debug`	todo lo que el servidor envía	todo, a medida que llega
`--log-level LEVEL`	todo lo que el servidor envía	solo notificaciones de LEVEL o superior
`--debug --log-level LEVEL`	todo lo que el servidor envía	stderr completo + notificaciones de LEVEL o superior

LEVEL es uno de debug, info, notice, warning, error, critical, alert, emergency.

Sin bandera, no se solicita ningún nivel: el servidor decide lo que emite y todo se registra. --log-level filtra lo que ve y también se envía al servidor (logging/setLevel) cuando anuncia la capacidad de registro — dicho servidor puede entonces dejar de emitir los niveles inferiores, que también faltan en el archivo. Los servidores sin esa capacidad siguen enviando todo y el filtrado ocurre aquí.

Cuando un servidor no puede conectarse, el error apunta a su archivo de registro: todo lo que el servidor imprimió en su salida está ahí, y esa suele ser la razón real.

[!NOTE] Lo que ollmcp mismo reporta va a ~/.config/ollmcp/logs/<session>/ollmcp.log, junto a los archivos del servidor. Se escribe en cada ejecución, sin necesidad de --debug, y es el archivo al que apunta la advertencia en pantalla cuando una transmisión de respuesta termina temprano. Trabajo en progreso: por ahora registra principalmente errores de proveedor y transmisión, y se registrará más allí con el tiempo.

Proveedores de inferencia compatibles

[!WARNING] Los proveedores que no son Ollama son experimentales. El soporte para proveedores distintos de Ollama se añadió recientemente y aún se está estabilizando; es posible que no todo funcione correctamente todavía.

ollmcp funciona con Ollama más cualquier proveedor compatible con OpenAI que any-llm exponga. Seleccione uno con --provider. Proporcione la clave con --api-key o $OLLMCP_API_KEY (ambas funcionan para cualquier proveedor seleccionado) o mediante la variable de entorno nativa del proveedor que se muestra a continuación. $OLLMCP_API_KEY y las variables de entorno nativas del proveedor nunca se escriben en disco; solo una clave pasada con --api-key se guarda en la configuración.

Proveedor (`--provider`)	Variable de entorno de clave API
`ollama` (predeterminado)	- (local)
`atlascloud`	`ATLASCLOUD_API_KEY`
`azureopenai`	`AZURE_OPENAI_API_KEY`
`dashscope`	`DASHSCOPE_API_KEY`
`databricks`	`DATABRICKS_TOKEN`
`deepinfra`	`DEEPINFRA_API_KEY`
`deepseek`	`DEEPSEEK_API_KEY`
`fireworks`	`FIREWORKS_API_KEY`
`gateway`	`GATEWAY_API_KEY`
`inception`	`INCEPTION_API_KEY`
`llama`	`LLAMA_API_KEY`
`llamacpp`	- (local)
`llamafile`	- (local)
`lmstudio`	`LM_STUDIO_API_KEY`
`minimax`	`MINIMAX_API_KEY`
`moonshot`	`MOONSHOT_API_KEY`
`mzai`	`ANY_LLM_KEY`
`nebius`	`NEBIUS_API_KEY`
`openai`	`OPENAI_API_KEY`
`openrouter`	`OPENROUTER_API_KEY`
`perplexity`	`PERPLEXITY_API_KEY`
`portkey`	`PORTKEY_API_KEY`
`qiniu`	`QINIU_API_KEY`
`sambanova`	`SAMBANOVA_API_KEY`
`vllm`	`VLLM_API_KEY`
`zai`	`ZAI_API_KEY`

[!NOTE] Los servidores locales compatibles con OpenAI (ollama, llamacpp, llamafile, lmstudio, vllm) normalmente se ejecutan sin clave API; apunte ollmcp a ellos con --host. Los proveedores que any-llm ofrece y que no son compatibles con OpenAI (p. ej. anthropic, gemini, mistral, groq, cohere) aún no son compatibles.

[!WARNING] Limitación de detección de capacidades: ollmcp solo lee capacidades reales por modelo (tools, vision, thinking) de Ollama. Para cada proveedor que no sea Ollama, actualmente se asume que las tres capacidades están disponibles y se muestran como tales en la lista de modelos y las insignias, por lo que un modelo puede reportarse como compatible con herramientas, visión o pensamiento incluso cuando no lo es. Si a un modelo le falta una capacidad, la API del proveedor devolverá un error cuando intente usarla.

Orden de resolución de la clave API

Para el proveedor seleccionado, ollmcp resuelve la clave API en este orden, de mayor a menor precedencia:

La bandera --api-key / -k.
La variable de entorno $OLLMCP_API_KEY (agnóstica al proveedor, se aplica a cualquier proveedor que seleccione con --provider).
La clave por proveedor guardada en ~/.config/ollmcp/config.json (presente solo si alguna vez se pasó mediante --api-key).
La variable de entorno nativa del propio proveedor, detectada por any-llm (p. ej. OPENAI_API_KEY, OPENROUTER_API_KEY).

[!WARNING] Una clave guardada por proveedor (3) tiene precedencia sobre la variable de entorno nativa del proveedor (4). Por lo tanto, si guardó previamente una clave incorrecta o caducada, establecer OPENAI_API_KEY (o el equivalente) por sí solo no la anulará. Para corregirlo, pase la clave correcta con --api-key, o elimine la apiKey obsoleta del perfil de ese proveedor en ~/.config/ollmcp/config.json.

Ejemplos de uso

La forma más sencilla de ejecutar el cliente:

ollmcp

[!TIP] Esto se conecta a todos los servidores registrados mediante ollmcp mcp add y usa el modelo de su archivo de configuración guardado, o el primer modelo disponible en Ollama si no hay ninguno guardado. Pase --claude-desktop para incluir también servidores de la configuración de Claude Desktop.

Conectarse a un solo servidor:

ollmcp --mcp-server /path/to/weather.py --model llama3.2:3b
# Or using short flags:
ollmcp -s /path/to/weather.py -m llama3.2:3b

Conectarse a múltiples servidores:

ollmcp --mcp-server /path/to/weather.py --mcp-server /path/to/filesystem.js
# Or using short flags:
ollmcp -s /path/to/weather.py -s /path/to/filesystem.js

[!TIP] Si --model no se especifica, se usa el modelo de su archivo de configuración guardado; de lo contrario, el primer modelo disponible en Ollama se selecciona automáticamente (se le indicará cómo descargar uno si no hay ninguno instalado).

Usar un archivo de configuración JSON:

ollmcp --servers-json /path/to/servers.json --model llama3.2:1b
# Or using short flags:
ollmcp -j /path/to/servers.json -m llama3.2:1b

[!TIP] Consulte la sección Formato de configuración de servidor para más detalles sobre cómo estructurar el archivo JSON.

Usar un host de Ollama personalizado:

ollmcp --host http://localhost:22545 --servers-json /path/to/servers.json
# Or using short flags:
ollmcp -H http://localhost:22545 -j /path/to/servers.json

Usar un proveedor de LLM diferente (OpenAI o cualquier API compatible con OpenAI):

ollmcp --provider openai --api-key $OPENAI_API_KEY --model gpt-5.5
# OpenAI-compatible providers (e.g. OpenRouter, DeepSeek); override the endpoint with --host if needed:
ollmcp --provider openrouter --api-key $OPENROUTER_API_KEY -m openrouter/free

[!TIP] La configuración del proveedor (modelo, host, clave API) se recuerda por proveedor. Una vez guardada con /save-config, el simple ollmcp reanuda su último proveedor usado. Consulte Gestión de configuración para más detalles.

Conectarse a servidores SSE o Streamable HTTP por URL:

ollmcp --mcp-server-url http://localhost:8000/sse --model qwen2.5:latest
# Or using short flags:
ollmcp -u http://localhost:8000/sse -m qwen2.5:latest

Conectarse a múltiples servidores por URL:

ollmcp --mcp-server-url http://localhost:8000/sse --mcp-server-url http://localhost:9000/mcp
# Or using short flags:
ollmcp -u http://localhost:8000/sse -u http://localhost:9000/mcp

Mezclar scripts locales y servidores por URL:

ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --model qwen3:1.7b
# Or using short flags:
ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp -m qwen3:1.7b

Incluir servidores de Claude Desktop junto con otras fuentes:

ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --claude-desktop
# Or using short flags:
ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp --claude-desktop

Cómo funcionan las llamadas a herramientas

El cliente envía tu consulta a Ollama con una lista de herramientas disponibles
Si Ollama decide usar una herramienta, el cliente:
- Muestra la ejecución de la herramienta con argumentos formateados y resaltado de sintaxis
- Muestra un mensaje de confirmación Human-in-the-Loop (si está habilitado) que te permite revisar y aprobar la llamada a la herramienta
- Extrae el nombre de la herramienta y los argumentos de la respuesta del modelo
- Llama al servidor MCP correspondiente con estos argumentos (solo si se aprueba o HIL está deshabilitado)
- Muestra la respuesta de la herramienta en un formato estructurado y fácil de leer (incluyendo resúmenes de imágenes y medios no compatibles)
- Si la herramienta devolvió imágenes y el modelo actual admite visión, adjunta las imágenes al siguiente mensaje del LLM; de lo contrario, muestra una advertencia
- Envía el resultado de la herramienta de vuelta a Ollama
- Si está en Modo Agente, repite el proceso si el modelo solicita más llamadas a herramientas
Finalmente, el cliente:
- Muestra la respuesta final del modelo incorporando los resultados de las herramientas

Modo Agente

Algunos modelos pueden solicitar múltiples llamadas a herramientas en una sola conversación. El cliente admite un Modo Agente que permite la ejecución iterativa de herramientas:

Cuando el modelo solicita una llamada a herramienta, el cliente la ejecuta y envía el resultado de vuelta al modelo
Este proceso se repite hasta que el modelo proporciona una respuesta final o alcanza el límite de iteraciones configurado
Puedes establecer el número máximo de iteraciones usando el comando /loop-limit (/ll)
El límite de bucle predeterminado es 7 para evitar bucles infinitos

Cuando se alcanza el límite de bucle

En lugar de detenerse silenciosamente, el cliente se pausa y te pregunta cómo proceder:

Opción	Tecla	Descripción
Continuar	`c` (predeterminado)	Otorgar otro lote de iteraciones (mismo tamaño que el límite actual)
Número	`n`	Elegir exactamente cuántas iteraciones más permitir
Ilimitado	`u`	Eliminar el límite y ejecutar hasta que el modelo deje de solicitar herramientas
Concluir	`w`	Pedir al modelo que resuma lo recopilado hasta ahora y produzca una respuesta final: conserva todos los resultados de herramientas recopilados antes del límite
Abortar	`a`	Descartar el turno por completo (nada se guarda en el historial)

[!NOTE] Si deseas evitar el uso del Modo Agente, simplemente establece el límite de bucle en 1.

Demo rápida del Modo Agente:

Comandos Interactivos

Durante el chat, usa estos comandos:

[!IMPORTANT] NUEVO: Los comandos interactivos integrados ahora requieren un / inicial.

Usa /help, /model, /tools, /prompts, etc.

Los nombres de comandos simples como help o model ya no se ejecutan como comandos.

Las invocaciones de prompts también usan /, con /server:prompt_name recomendado para evitar colisiones.

ollmcp main interface

Comando	Atajo	Descripción
`abort`	`a`	Mientras el modelo está generando, aborta la generación de la respuesta actual
`/clear`, `/new`	`/cc`	Borrar el historial de conversación y el contexto
`/cls`	`/clear-screen`	Limpiar la pantalla del terminal
`/context`	`/c`	Alternar la retención de contexto
`/context-info`	`/ci`	Mostrar estadísticas de contexto
`/export-history`	`/eh`	Exportar el historial de chat a un archivo JSON
`/full-history`	`/fh`	Mostrar todo el historial de conversación
`/help`	`/h`	Mostrar ayuda y comandos disponibles
`/import-history`	`/ih`	Importar historial de chat desde un archivo JSON
`/human-in-the-loop`	`/hil`	Alternar confirmaciones Human-in-the-Loop para la ejecución de herramientas
`/load-config`	`/lc`	Cargar configuración de herramientas y modelo desde un archivo
`/loop-limit`	`/ll`	Establecer el máximo de iteraciones de bucle de herramientas (Modo Agente). Predeterminado: 7
`/model`	`/m`	Listar y seleccionar un modelo de Ollama diferente
`/model-config`	`/mc`	Configurar parámetros avanzados del modelo y el prompt del sistema
`/display-mode`	`/dm`	Elegir modos de visualización de respuestas: Plano, Markdown, Ambos o Markdown (bloques)
`/input-mode`	`/im`	Elegir modo de entrada de chat de una línea o multilínea
`/prompts`	`/pr`	Explorar y ver todos los prompts MCP disponibles
`/server:prompt_name`	`/prompt_name`	Invocar un prompt (se recomienda el calificado)
`/resources`	`/res`	Explorar y ver todos los recursos MCP disponibles
`@uri`	-	Leer un recurso específico por URI (por ejemplo, `@server://info`)
`/quit`, `/exit`, `/bye`	`/q`, `Ctrl+C`, o `Ctrl+D`	Salir del cliente
`/reload-servers`	`/rs`	Recargar todos los servidores MCP con la configuración actual
`/reset-config`	`/rc`	Restablecer la configuración a los valores predeterminados (todas las herramientas habilitadas)
`/save-config`	`/sc`	Guardar la configuración actual de herramientas y modelo en un archivo
`/show-metrics`	`/sm`	Alternar la visualización de métricas de rendimiento
`/show-thinking`	`/st`	Alternar la visibilidad del texto de pensamiento (visible por defecto)
`/thinking-mode`	`/tm`	Alternar el modo de pensamiento en modelos compatibles
`/reasoning-effort`	`/re`	Establecer el nivel de esfuerzo de razonamiento (auto/minimal/low/medium/high/xhigh) cuando el modo de pensamiento está activado. Predeterminado: medium
`/show-tool-execution`	`/ste`	Alternar la visibilidad de la visualización de ejecución de herramientas
`/tools`	`/t`	Abrir la interfaz de selección de herramientas

Herramientas MCP

La interfaz de selección de herramientas y servidores te permite habilitar o deshabilitar herramientas específicas:

ollmcp tool and server selection interface

Ingresa números separados por comas (por ejemplo, 1,3,5) para alternar herramientas específicas
Ingresa rangos de números (por ejemplo, 5-8) para alternar múltiples herramientas consecutivas
Ingresa S + número (por ejemplo, S1) para alternar todas las herramientas en un servidor específico
a o all - Habilitar todas las herramientas
n o none - Deshabilitar todas las herramientas
d o desc - Mostrar/ocultar descripciones de herramientas
j o json - Mostrar esquemas JSON detallados de herramientas en las herramientas habilitadas con fines de depuración
s o save - Guardar cambios y volver al chat
q o quit - Cancelar cambios y volver al chat

Prompts MCP

Los Prompts MCP proporcionan iniciadores de conversación y plantillas de contexto reutilizables definidos por el servidor. Los servidores pueden exponer prompts con descripciones, argumentos requeridos y mensajes preformateados que te ayudan a iniciar rápidamente tipos específicos de conversaciones o inyectar contexto estructurado en tu chat.

Características

📋 Explorar Prompts: Ver todos los prompts disponibles de los servidores conectados con descripciones y requisitos de argumentos
⚡️ Invocación Rápida: Usa la sintaxis de barra para invocar prompts (/server:prompt_name recomendado)
🔤 Autocompletado: Escribe / para ver sugerencias de prompts con coincidencia difusa
📝 Recopilación de Argumentos: Los prompts interactivos te guían a través de los parámetros requeridos
👁️ Vista Previa: Revisa el contenido del prompt antes de la inyección para asegurarte de que se ajusta a tus necesidades
🎯 Inyección Flexible: Elige ejecutar inmediatamente o solo inyectar (agregar al historial sin activar el modelo)
🧠 Consciente del Contexto: Se adapta automáticamente según si el prompt termina con un mensaje de usuario o de asistente
🔄 Reversión Segura: Limpieza automática del historial si abortas o encuentras errores
💬 Contenido de Texto: Admite mensajes de prompt basados en texto (soporte de imagen/audio/recurso próximamente)

Cómo Usar Prompts MCP

Explorar Prompts Disponibles:

/prompts  # or '/pr'

Esto muestra todos los prompts agrupados por servidor, mostrando sus nombres, argumentos requeridos y descripciones.

Invocar un Prompt:

/server:prompt_name

Por ejemplo, si un servidor llamado docs proporciona un prompt "summarize":

/docs:summarize

Si un nombre de prompt es único entre los servidores conectados, puedes usar la forma corta:

/summarize

Si múltiples servidores exponen el mismo nombre de prompt, el cliente te pedirá que uses la forma calificada y sugerirá opciones válidas de /server:prompt_name.

Autocompletado:

Escribe / para ver todos los prompts disponibles con descripciones
Continúa escribiendo para filtrar prompts con coincidencia difusa
Usa las teclas de flecha para navegar y presiona Enter para seleccionar

[!TIP] Los prompts se descubren automáticamente cuando te conectas a servidores MCP. Si un servidor admite prompts, estarán disponibles inmediatamente en la lista de prompts y en el autocompletado.

Flujo de Trabajo:

Escribe /server:prompt_name (recomendado) o selecciona desde el autocompletado
Si el prompt requiere argumentos, se te pedirá que los proporciones
Revisa la vista previa del prompt que muestra lo que se inyectará
Elige cómo usar el prompt:
- y/yes (predeterminado): Enviar el prompt al modelo y obtener una respuesta
  - Para prompts que terminan con un mensaje de usuario: Usa ese mensaje como consulta
  - Para prompts que terminan con un mensaje de asistente: Agrega "Por favor responde basándote en el contexto anterior." como consulta
- i/inject: Solo agregar el prompt al historial de conversación sin activar el modelo (te permite escribir tu propia consulta después)
- n/no: Cancelar y volver al chat
El prompt se inyecta según tu elección
Si abortas durante la generación del modelo (presiona 'a'), los cambios se revierten automáticamente

Ejemplo: ollmcp prompt feature screenshot

[!WARNING] Limitaciones de Tipos de Contenido: Los Prompts MCP actualmente admiten solo contenido de texto. Los siguientes tipos de contenido aún no son compatibles y se omitirán automáticamente:

🖼️ Imágenes - Contenido de imagen en prompts

🎵 Audio - Contenido de audio en prompts

📦 Recursos - Contenido de recursos incrustados

Recursos MCP

Los Recursos MCP proporcionan acceso a datos contextuales expuestos por servidores MCP: archivos, documentos, datos estructurados y más. Los servidores pueden exponer recursos con metadatos (nombre, descripción, tipo MIME) que puedes explorar y leer en tu contexto de conversación.

Características

📋 Explorar Recursos: Ver todos los recursos disponibles de los servidores conectados con URIs, nombres, tipos MIME y descripciones
📖 Leer Recursos: Usa la sintaxis @uri para leer contenido de recursos, de forma independiente o en línea dentro de una consulta
📝 Contenido de Texto: Soporte completo para recursos basados en texto (markdown, código, registros, etc.)
🖼️ Soporte de Imágenes para Visión: Los recursos de imagen (image/*) se reenvían automáticamente como imágenes base64 a modelos con capacidad de visión
🎯 Inyección de Contexto: El contenido del recurso se almacena en búfer y se inyecta como contexto junto con tu próxima consulta
🔍 Autocompletado: Escribe @ para ver sugerencias de recursos y plantillas disponibles con coincidencia difusa
🛡️ Seguridad Binaria: El contenido binario que no es imagen (audio, video, PDFs, archivos comprimidos) se detecta y se omite elegantemente con mensajes informativos

Cómo Usar Recursos MCP

Explorar recursos disponibles:

/resources  # or '/res'

Esto muestra todos los recursos y plantillas agrupados por servidor, mostrando URIs, nombres, tipos MIME y descripciones. Los recursos binarios están marcados con una etiqueta [binary] y las plantillas con una etiqueta [template].

Leer un recurso:

@<uri>

Por ejemplo, para leer un recurso de archivo:

@file:///path/to/document.md

Hay dos formas de usar @uri:

1. Independiente (buffer y luego consulta): Escribe @uri solo. El recurso se obtiene y se almacena en el buffer. Luego escribe tu consulta en el siguiente mensaje. El contenido del recurso se inyecta automáticamente como contexto.

2. En línea (una sola interacción): Incluye @uri en cualquier parte del texto de tu consulta. El recurso se obtiene y la consulta se procesa inmediatamente en un solo paso.

Ejemplo independiente:

qwen3/show-thinking/6-tools❯ @server://info
✅ Read resource 'get_server_info' (197 chars)

Preview:
This is a simple MCP server with streamable HTTP transport. It supports tools for greeting, adding numbers, generating
random numbers, and calculating BMI. It also provides a BMI calculator prompt.

1 resource(s) buffered. Type your query, or include @another_uri inline.

qwen3/show-thinking/6-tools❯ Next question here

Ejemplo en línea:

qwen3/show-thinking/6-tools❯ summarize the key features from @server://info
✅ Read resource 'get_server_info' (197 chars)

Preview:
This is a simple MCP server with streamable HTTP transport. It supports tools for greeting, adding numbers, generating
random numbers, and calculating BMI. It also provides a BMI calculator prompt.
[model response]

[!TIP] Los recursos se descubren automáticamente cuando te conectas a los servidores MCP. Si un servidor admite recursos, estarán disponibles inmediatamente en la lista resources y en el autocompletado de @.

[!NOTE] 🖼️ Las imágenes (image/*) están admitidas; se pasan directamente a los modelos con capacidad de visión como datos base64. Contenido binario: Los siguientes tipos de recursos no se admiten como contexto y se omitirán con un mensaje informativo:

🎵 Audio - Tipos MIME audio/*

📹 Video - Tipos MIME video/*

📄 PDFs - application/pdf

🗜️ Archivos comprimidos - application/zip, application/octet-stream

Modos de visualización de respuestas

El comando /display-mode (/dm) te permite elegir cómo se muestran las respuestas del modelo mientras se transmiten:

Texto plano: Transmite la respuesta una vez como texto plano sin volver a renderizar el markdown final
✨NUEVO Markdown (predeterminado): Transmite markdown formateado línea por línea: las líneas por encima de una pequeña cola en vivo se imprimen una vez y nunca se vuelven a dibujar, por lo que sigue siendo confiable incluso con emojis o cambios de tamaño de terminal
Ambos: Primero transmite texto plano y luego renderiza la respuesta completa nuevamente como markdown
Markdown (bloques): Renderiza la respuesta como markdown un bloque a la vez; cada párrafo/lista/tabla/bloque de código se imprime una vez cuando se completa y nunca se vuelve a dibujar, por lo que no puede duplicar líneas

Usa /display-mode o /dm durante el chat para abrir el selector interactivo.

Por qué podrías cambiar de modo:

Texto plano es la opción menos ruidosa si deseas un redibujado o parpadeo mínimo
Markdown combina la transmisión línea por línea con un formato markdown coherente; como máximo, las últimas líneas se vuelven a dibujar, por lo que los fallos permanecen acotados incluso con emojis o cambios de tamaño
Ambos te brinda retroalimentación rápida de transmisión más una representación final limpia en markdown
Markdown (bloques) es la forma más conservadora de ver markdown formateado mientras se transmite, a costa de actualizaciones bloque por bloque (en lugar de línea por línea)

[!TIP] Tu modo de visualización seleccionado se guarda con /save-config y se restaura con /load-config, para que puedas mantener diferentes preferencias de visualización para diferentes flujos de trabajo.

Modo de entrada

El comando /input-mode (/im) controla cómo escribes los mensajes de chat:

Una línea (predeterminado): Presiona Enter para enviar inmediatamente después de escribir tu mensaje
Multilínea: Presiona Enter para agregar una nueva línea y luego presiona Esc seguido de Enter para enviar el mensaje completo cuando hayas terminado. Esto permite mensajes más complejos con varios párrafos o bloques de código.
Ctrl+J también inserta una nueva línea en modo multilínea como una alternativa confiable en todos los terminales

Usa /input-mode o /im durante el chat para abrir el selector interactivo.

[!IMPORTANT] Los atajos de envío multilínea pueden variar según el emulador de terminal y el manejo del teclado del sistema operativo. Este cliente depende de Esc y luego Enter como el atajo de envío portátil en modo multilínea. Shift+Enter y Meta+Enter pueden funcionar en algunos terminales, pero no están garantizados.

Selección de modelo

La interfaz de selección de modelo muestra todos los modelos disponibles en tu instalación de Ollama:

ollmcp model selection interface

Ingresa el número del modelo que deseas usar
s o save - Guarda la selección del modelo y vuelve al chat
q o quit - Cancela la selección del modelo y vuelve al chat

Configuración avanzada del modelo

El comando /model-config (/mc) abre la interfaz de configuración avanzada del modelo, lo que te permite ajustar cómo el modelo genera respuestas:

ollmcp model configuration interface

Mensaje del sistema

Mensaje del sistema: Establece el rol y el comportamiento del modelo para guiar las respuestas.

Parámetros clave

Ventana de contexto (num_ctx): Establece cuánto historial de chat usa el modelo. Equilibra con el uso de memoria y el rendimiento.
Tokens a conservar: Evita que se eliminen tokens importantes
Máximo de tokens: Limita la longitud de la respuesta (0 = automático)
Semilla: Hace que las salidas sean reproducibles (configúrala en -1 para aleatorio)
Temperatura: Controla la aleatoriedad (0 = determinista, más alto = creativo)
Top K / Top P / Min P / Typical P: Controles de muestreo para la diversidad
Repetir últimos N / Penalización de repetición: Reduce la repetición
Penalización de presencia/frecuencia: Fomenta nuevos temas, reduce repeticiones
Secuencias de parada: Puntos de parada personalizados (hasta 8)
Tamaño de lote (num_batch): Controla el procesamiento interno por lotes de las solicitudes; los valores más grandes pueden aumentar el rendimiento pero usar más memoria.

Comandos

Ingresa los números de parámetros 1-15 para editar la configuración
Ingresa sp para editar el mensaje del sistema
Usa u1, u2, etc. para anular parámetros, o uall para restablecer todo
h/help: Muestra detalles y consejos de los parámetros
undo: Revierte los cambios
s/save: Aplica los cambios
q/quit: Cancela

Ejemplos de configuración

Factual: temperature: 0.0-0.3, top_p: 0.1-0.5, seed: 42
Creativo: temperature: 1.0+, top_p: 0.95, presence_penalty: 0.2
Reducir repeticiones: repeat_penalty: 1.1-1.3, presence_penalty: 0.2, frequency_penalty: 0.3
Equilibrado: temperature: 0.7, top_p: 0.9, typical_p: 0.7
Reproducible: seed: 42, temperature: 0.0
Contexto amplio: num_ctx: 8192 o más para conversaciones complejas que requieran más contexto

[!TIP] Todos los parámetros están sin configurar de forma predeterminada, lo que permite que Ollama use sus propios valores optimizados. Usa help en el menú de configuración para obtener detalles y recomendaciones. Los cambios se guardan con tu configuración.

Modo de pensamiento y esfuerzo de razonamiento

Habilita el modo de pensamiento con /thinking-mode (/tm) para activar el razonamiento extendido en modelos compatibles (por ejemplo, qwen3, deepseek-r1, Claude con pensamiento extendido). Usa /show-thinking (/st) para alternar si el proceso de razonamiento es visible en la respuesta.

Usa /reasoning-effort (/re) para controlar cuánto esfuerzo de razonamiento aplica el modelo cuando el modo de pensamiento está activado:

Nivel	Descripción
`auto`	Esfuerzo predeterminado del proveedor (recomendado para la nube)
`minimal`	Más rápido, menos razonamiento
`low`	Razonamiento ligero
`medium`	Equilibrado — predeterminado
`high`	Razonamiento más exhaustivo
`xhigh`	Esfuerzo de razonamiento máximo

[!NOTE] Algunos proveedores o modelos pueden ignorar la configuración del esfuerzo de razonamiento.

Recarga de servidores para desarrollo

El comando /reload-servers (/rs) es particularmente útil durante el desarrollo de servidores MCP. Te permite recargar todos los servidores conectados sin reiniciar toda la aplicación cliente.

Beneficios clave:

🔄 Recarga en caliente: Aplica instantáneamente los cambios al código de tu servidor MCP
🛠️ Flujo de trabajo de desarrollo: Perfecto para el desarrollo y las pruebas iterativas
📝 Actualizaciones de configuración: Detecta automáticamente los cambios en las configuraciones JSON del servidor o en las configuraciones de Claude
🎯 Preservación del estado: Mantiene tus preferencias de herramientas habilitadas/deshabilitadas entre recargas
⚡️ Ahorro de tiempo: No es necesario reiniciar el cliente y reconfigurar todo

Cuándo usarlo:

Después de modificar la implementación de tu servidor MCP
Cuando hayas actualizado las configuraciones del servidor en archivos JSON
Después de cambiar la configuración MCP de Claude
Durante la depuración para asegurarte de que estás probando la versión más reciente del servidor

Simplemente escribe /reload-servers o /rs en la interfaz de chat, y el cliente:

Se desconectará de todos los servidores MCP actuales
Se reconectará usando los mismos parámetros (servidores agregados mediante ollmcp mcp add, rutas de servidor, archivos de configuración, --claude-desktop)
Restaurará tus configuraciones anteriores de herramientas habilitadas/deshabilitadas
Mostrará el estado actualizado del servidor y las herramientas

Esta función mejora drásticamente la experiencia de desarrollo al crear y probar servidores MCP.

Ejecución de herramientas con intervención humana (HIL)

La función de intervención humana proporciona una capa de seguridad adicional al permitirte revisar y aprobar las ejecuciones de herramientas antes de que se ejecuten. Esto es particularmente útil para:

🛡️ Seguridad: Revisa operaciones potencialmente destructivas antes de la ejecución
🔍 Aprendizaje: Comprende qué herramientas quiere usar el modelo y por qué
🎯 Control: Ejecución selectiva solo de las herramientas que apruebes
🚫 Prevención: Detén las llamadas a herramientas no deseadas
🔄 Modo de sesión: Aprueba automáticamente todas las herramientas para la sesión de consulta actual
🛑 Cancelación de consulta: Cancela toda la consulta sin guardarla en el historial

Pantalla de confirmación HIL

Cuando HIL está habilitado, verás un mensaje de confirmación antes de cada ejecución de herramienta:

Ejemplo:

ollmcp HIL confirmation screenshot

Opciones de confirmación HIL

Cuando se te solicite, puedes elegir entre las siguientes opciones:

y/yes: Ejecuta esta llamada de herramienta específica
n/no: Omite esta llamada de herramienta y continúa con la consulta
s/session: Ejecuta esta y todas las llamadas de herramienta posteriores para la consulta actual sin más avisos
d/disable: Deshabilita permanentemente las confirmaciones HIL (se pueden volver a habilitar con el comando /hil)
a/abort: Cancela toda la consulta inmediatamente sin guardarla en el historial

[!TIP] La opción sesión es particularmente útil cuando el modelo necesita ejecutar varias herramientas en secuencia. En lugar de confirmar cada una individualmente, puedes aprobar todas las herramientas para la sesión de consulta actual, y luego HIL se restablecerá automáticamente para la siguiente consulta.

Configuración de intervención humana (HIL)

Estado predeterminado: Las confirmaciones HIL están habilitadas de forma predeterminada por seguridad
Comando de alternancia: Usa /human-in-the-loop o /hil para activar/desactivar
Configuración persistente: La preferencia HIL se guarda con tu configuración
Desactivación rápida: Elige "disable" durante cualquier confirmación para desactivarla permanentemente
Aprobación automática de sesión: Usa "session" durante la confirmación para aprobar todas las herramientas de la consulta actual
Cancelación de consulta: Usa "abort" durante la confirmación para detener inmediatamente la consulta sin guardarla
Reactivación: Usa el comando /hil en cualquier momento para volver a activar las confirmaciones

Beneficios:

Seguridad mejorada: Previene ejecuciones de herramientas accidentales o no deseadas
Conciencia: Comprende qué acciones intenta realizar el modelo
Control selectivo: Elige qué operaciones permitir caso por caso
Flujo de trabajo flexible: Modo de sesión para consultas eficientes con múltiples herramientas, aprobación individual para operaciones sensibles
Cancelación limpia: Detén consultas problemáticas inmediatamente sin contaminar el historial de conversación
Tranquilidad: Visibilidad y control total sobre las acciones automatizadas

Métricas de rendimiento

La función de métricas de rendimiento muestra datos detallados del rendimiento del modelo después de cada consulta en un panel con bordes. Las métricas muestran tiempos de duración, recuentos de tokens y tasas de generación directamente de la respuesta de Ollama. Métricas mostradas:

total duration: Tiempo total dedicado a generar la respuesta completa (segundos)
load duration: Tiempo dedicado a cargar el modelo (milisegundos)
prompt eval count: Número de tokens en el prompt de entrada
prompt eval duration: Tiempo dedicado a evaluar el prompt de entrada (milisegundos)
eval count: Número de tokens generados en la respuesta
eval duration: Tiempo dedicado a generar los tokens de respuesta (segundos)
prompt eval rate: Velocidad de procesamiento del prompt de entrada (tokens/segundo)
eval rate: Velocidad de generación de tokens de respuesta (tokens/segundo)

Ejemplo: ollmcp ollama performance metrics screenshot

Configuración de métricas de rendimiento

Estado predeterminado: Las métricas están deshabilitadas por defecto para una salida más limpia
Comando de alternancia: Use /show-metrics o /sm para habilitar/deshabilitar la visualización de métricas
Configuración persistente: La preferencia de métricas se guarda con su configuración

Beneficios:

Monitoreo de rendimiento: Realice un seguimiento de la eficiencia del modelo y los tiempos de respuesta
Seguimiento de tokens: Monitoree el consumo real de tokens para análisis
Evaluación comparativa: Compare el rendimiento entre diferentes modelos

[!NOTE] Fuente de datos: Todas las métricas provienen directamente de la respuesta de Ollama, lo que garantiza precisión y confiabilidad.

Gestión del historial

La función de Gestión del historial le permite ver, exportar e importar su historial de conversaciones. Esto es útil para:

📜 Vista de historial completo: Revise todas las conversaciones de su sesión actual
💾 Exportar: Guarde conversaciones en archivos JSON para respaldo o análisis
📥 Importar: Cargue el historial de conversaciones anterior para continuar donde lo dejó
🔄 Portabilidad: Comparta o transfiera conversaciones entre sesiones

Comandos del historial

Ver historial completo:

/full-history  # or '/fh'

Muestra todo el historial de conversaciones de la sesión actual en una vista formateada, mostrando tanto consultas como respuestas.

Exportar historial:

/export-history  # or '/eh'

Exporta su historial de chat actual a un archivo JSON. Puede especificar un nombre de archivo personalizado o usar el nombre predeterminado basado en marca de tiempo (p. ej., ollmcp_chat_history_2026-01-05_143022.json). Los archivos se guardan en el directorio ~/.config/ollmcp/history/. El comando incluye protección contra sobrescritura de archivos.

Importar historial:

/import-history  # or '/ih'

Importa un historial de chat exportado previamente desde un archivo JSON. El comando valida la estructura JSON para garantizar la compatibilidad. El historial importado se agrega a su contexto de conversación actual.

Almacenamiento del historial:

Ubicación de exportación: ~/.config/ollmcp/history/
Formato de nombre de archivo predeterminado: ollmcp_chat_history_YYYY-MM-DD_HHMMSS.json
El formato JSON incluye tanto consultas como respuestas con validación de estructura adecuada

Beneficios:

Continuidad de sesión: Reanude conversaciones en diferentes sesiones
Respaldo: Mantenga registros de conversaciones importantes
Análisis: Exporte el historial para análisis o revisión externa
Compartir: Comparta el contexto de conversación con miembros del equipo
Pruebas: Importe conversaciones de prueba para desarrollo y depuración

[!TIP] Al exportar, si no proporciona un nombre de archivo, el sistema genera automáticamente un nombre de archivo con marca de tiempo para evitar sobrescrituras accidentales.

Funciones de autocompletado y prompt

Autocompletado de shell Typer

La CLI admite autocompletado de shell para todas las opciones y argumentos mediante Typer
Para habilitarlo, ejecute ollmcp --install-completion y siga las instrucciones para su shell
Disfrute del autocompletado con tabulador para todas las opciones agrupadas y generales

Autocompletado estilo FZF

Autocompletado de espacio de nombres con barra para comandos y prompts (/)
Descripciones de comandos mostradas en el menú
Coincidencia sin distinción de mayúsculas y minúsculas para mayor comodidad
Lista de comandos centralizada para consistencia
La escritura de consultas en texto plano está intencionalmente libre de ruido de autocompletado de acciones

Autocompletado de prompts MCP

Escriba / para activar el autocompletado de prompts
Coincidencia difusa en nombres y descripciones de prompts
Admite referencias de prompts calificadas como /server:prompt_name
Muestra descripciones de prompts en el menú
Los argumentos de prompts se recopilan durante la invocación del prompt (no se muestran en las filas de autocompletado)
Truncamiento de descripciones consciente del ancho de la terminal

Prompt contextual

El prompt de chat ahora le brinda información contextual clara de un vistazo:

Modelo: Muestra el modelo Ollama actual en uso
Modo de pensamiento: Indica si el "modo de pensamiento" está activo (para modelos compatibles)
Herramientas: Muestra la cantidad de herramientas habilitadas

Ejemplo de prompt:

qwen3/show-thinking/12-tools❯

qwen3 Nombre del modelo
/show-thinking Indicador de modo de pensamiento (si está habilitado; de lo contrario, /thinking u omitido)
/12-tools Cantidad de herramientas habilitadas (o /1-tool para singular)
❯ Símbolo del prompt

Esto facilita ver su contexto actual antes de ingresar una consulta.

[!TIP] Escriba / después del símbolo del prompt para ver sugerencias de autocompletado para los prompts MCP disponibles.

Gestión de configuración

[!TIP] Ejecutar ollmcp sin banderas carga automáticamente la configuración predeterminada desde ~/.config/ollmcp/config.json si existe.

El cliente guarda y carga sus preferencias entre sesiones:

Al usar /save-config, puede proporcionar un nombre para la configuración o usar el predeterminado
Las configuraciones se almacenan en el directorio ~/.config/ollmcp/
La configuración predeterminada se guarda como ~/.config/ollmcp/config.json
Las configuraciones con nombre se guardan como ~/.config/ollmcp/{name}.json

Perfiles por proveedor

La configuración de conexión se almacena por proveedor, por lo que cambiar de proveedor nunca reutiliza el modelo, host o clave API de otro proveedor. Cada proveedor mantiene su propio:

Modelo seleccionado
Host / URL base de API
Clave API

La configuración también registra un defaultProvider. Cuando ejecuta ollmcp sin la bandera --provider, carga el perfil de ese proveedor; una instalación nueva comienza en ollama. Cada vez que /save-config, el proveedor que está usando actualmente se convierte en el nuevo predeterminado, por lo que ejecutar ollmcp simple reanuda donde lo dejó. Pase --provider <name> en cualquier momento para cambiar a (y cargar) el perfil de un proveedor diferente, y --model / --host / --api-key anulan los valores guardados para esa ejecución.

[!NOTE] Solo una clave pasada con --api-key se almacena, en texto plano, en ~/.config/ollmcp/config.json. Las claves proporcionadas a través de la variable de entorno $OLLMCP_API_KEY o una variable de entorno nativa del proveedor (por ejemplo, OPENROUTER_API_KEY) nunca se escriben en el disco; use una de esas si no desea que su clave se persista.

La siguiente configuración se comparte entre todos los proveedores:

Parámetros avanzados del modelo (prompt del sistema, temperatura, configuración de muestreo, etc.)
Estado habilitado/deshabilitado de todas las herramientas
Configuración de retención de contexto
Configuración del modo de pensamiento
Preferencia del modo de visualización de respuestas
Preferencias de visualización de ejecución de herramientas
Preferencias de visualización de métricas de rendimiento
Configuración de confirmación Human-in-the-Loop

Ejemplo ~/.config/ollmcp/config.json:

{
  "defaultProvider": "openai",
  "providers": {
    "ollama": { "host": "http://localhost:11434", "model": "qwen3:1.7b", "apiKey": "" },
    "openai": { "host": "", "model": "gpt-5.5", "apiKey": "sk-..." }
  },
  "enabledTools": {},
  "modelConfig": {},
  "...": "shared settings"
}

[!TIP] Los archivos de configuración planos más antiguos (con host/model/provider/apiKey de nivel superior) se migran automáticamente la primera vez que ejecuta esta versión y se reescriben en el formato por proveedor en su próximo /save-config.

Formato de configuración del servidor

El archivo de configuración JSON admite tipos de servidor STDIO, SSE y Streamable HTTP (MCP 1.10.1):

{
  "mcpServers": {
    "stdio-server": {
      "command": "command-to-run",
      "args": ["arg1", "arg2", "..."],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "disabled": false
    },
    "sse-server": {
      "type": "sse",
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      },
      "disabled": true
    },
    "http-server": {
      "type": "streamable_http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      },
      "disabled": false
    }
  }
}

[!NOTE] Soporte de transporte MCP 1.10.1: El cliente ahora admite el transporte Streamable HTTP más reciente con rendimiento y confiabilidad mejorados. Si especifica una URL sin tipo, el cliente usará por defecto el transporte Streamable HTTP.

Consejos: dónde colocar las configuraciones del servidor MCP y un ejemplo funcional

Un punto común de confusión es dónde almacenar los archivos de configuración del servidor MCP y cómo se usa la función de guardar/cargar de la TUI. Aquí hay una guía breve y práctica que ha ayudado a otros usuarios:

Los comandos /save-config / /load-config (o /sc / /lc) de la TUI están destinados a guardar preferencias de la TUI como qué herramientas habilitó, su modelo seleccionado, modo de pensamiento, modo de visualización y otras configuraciones del lado del cliente. No son necesarios para registrar conexiones de servidor MCP con el cliente.
Para archivos JSON de servidor MCP (el objeto mcpServers que se muestra arriba), recomendamos mantenerlos fuera del directorio de configuración de la TUI o en una subcarpeta clara, por ejemplo:

~/.config/ollmcp/mcp-servers/config.json

Luego puede apuntar ollmcp a ese archivo al inicio con -j / --servers-json.

[!IMPORTANT] Para servidores MCP basados en HTTP, "type": "http", "streamable-http" y "streamable_http" se aceptan y se tratan de la misma manera. También consulte la sección Rutas de endpoint MCP comunes a continuación para ver endpoints típicos.

Aquí hay un ejemplo mínimo funcional, digamos que este es su ~/.config/ollmcp/mcp-servers/config.json:

{
  "mcpServers": {
    "github": {
      "type": "streamable_http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer mytoken"
      }
    }
  }
}

[!TIP] Al usar el servidor MCP de GitHub, asegúrese de reemplazar "mytoken" con su token API real de GitHub.

Con ese archivo en su lugar, puede conectarse usando:

ollmcp -j ~/.config/ollmcp/mcp-servers/config.json

Aquí puede encontrar un problema de GitHub relacionado con este error común: https://github.com/jonigl/mcp-client-for-ollama/issues/112#issuecomment-3446569030

Demo

Una demo corta (asciicast) que debería ayudar a cualquiera a reproducir la configuración funcional rápidamente. Este ejemplo usa un ejemplo de servidor MCP con protocolo HTTP streamable:

Rutas de endpoint MCP comunes

Los servidores MCP Streamable HTTP típicamente exponen el endpoint MCP en /mcp (p. ej., https://host/mcp), mientras que los servidores SSE comúnmente usan /sse (p. ej., https://host/sse). A continuación se muestra un extracto de la especificación MCP (2025-06-18):

El servidor DEBE proporcionar una única ruta de endpoint HTTP (en adelante denominada endpoint MCP) que admita métodos POST y GET. Por ejemplo, esto podría ser una URL como https://example.com/mcp.

Puede encontrar más detalles en la especificación MCP versión 2025-06-18 - Transports.

[!NOTE] Los certificados HTTPS para servidores MCP remotos se verifican contra su almacén de confianza del sistema operativo, no contra el paquete certifi. Si un servidor MCP está detrás de una CA privada o corporativa, o ejecuta ollmcp en un contenedor mínimo sin almacén de CA del sistema, el protocolo de enlace TLS falla con un error que no menciona ollmcp. Apunte SSL_CERT_FILE (un archivo de paquete) o SSL_CERT_DIR (un directorio) a su CA para solucionarlo:
export SSL_CERT_FILE=/path/to/corporate-ca.pem

Modelos compatibles

Los siguientes modelos Ollama funcionan bien con el uso de herramientas:

gemma4
qwen3.5
lfm2.5-thinking
llama3.2
mistral

Para una lista completa de modelos Ollama con capacidades de uso de herramientas, visite la página oficial de modelos Ollama.

Para modelos que también pueden procesar imágenes devueltas por herramientas, consulte la página de modelos de visión Ollama.

Modelos Ollama Cloud

MCP Client for Ollama ahora admite modelos Ollama Cloud, lo que le permite usar potentes modelos alojados en la nube con capacidades de llamada a herramientas mientras aprovecha sus herramientas MCP locales. Los modelos en la nube pueden ejecutarse sin una GPU local potente, lo que hace posible acceder a modelos más grandes que no cabrían en una computadora personal.

Los modelos Ollama Cloud compatibles incluyen, por ejemplo:

gpt-oss:20b-cloud
gpt-oss:120b-cloud
deepseek-v3.1:671b-cloud
qwen3-coder:480b-cloud

Para usar modelos Ollama Cloud con este cliente:

Primero, extraiga el modelo en la nube:
```
ollama pull gpt-oss:120b-cloud
```
Ejecute el cliente con su modelo en la nube elegido:
```
ollmcp --model gpt-oss:120b-cloud
```

[!NOTE] El modelo deepseek-v3.1:671b-cloud solo admite el uso de herramientas cuando el modo de pensamiento está desactivado. Puede alternar el modo de pensamiento en ollmcp escribiendo /thinking-mode o /tm.

Para obtener más información sobre Ollama Cloud, visite la documentación de Ollama Cloud.

Patrocinadores

Este proyecto cuenta con el apoyo de:

Atlas Cloud

Atlas Cloud es una plataforma de inferencia de IA multimodal: una única API de IA con acceso unificado a más de 300 modelos seleccionados para cargas de trabajo de video, imagen y LLM.

Funciona con ollmcp de forma inmediata:

ollmcp --provider atlascloud --api-key YOUR_ATLASCLOUD_API_KEY
# or export the key once and skip the flag:
export ATLASCLOUD_API_KEY=YOUR_ATLASCLOUD_API_KEY
ollmcp --provider atlascloud

El streaming y la llamada a herramientas son totalmente compatibles, y puedes explorar y elegir cualquiera de los modelos de Atlas Cloud con el comando interactivo /model.

Conviértete en patrocinador

¿Quieres ver tu logo aquí? Apoya el proyecto a través de GitHub Sponsors ❤️

¿Dónde puedo encontrar más servidores MCP?

Puedes explorar una colección de servidores MCP en el repositorio oficial de servidores MCP.

Este repositorio contiene implementaciones de referencia para el Protocolo de Contexto de Modelo, servidores creados por la comunidad y recursos adicionales para mejorar las capacidades de herramientas de tu LLM.

Proyectos relacionados

Ollama MCP Bridge - Una capa de API de Python que se sitúa frente a Ollama, añadiendo automáticamente herramientas de múltiples servidores MCP a cada solicitud de chat. Este proyecto proporciona una solución de proxy transparente que precarga todos los servidores MCP al inicio e integra sus herramientas sin problemas en la API de Ollama.
Ejemplo de servidor MCP con HTTP transmisible - Un servidor MCP de ejemplo que demuestra el uso del protocolo HTTP transmisible.

Seguridad

Los servidores MCP a los que te conectas son de tu confianza, y sus respuestas de herramientas/recursos se tratan como contenido no confiable que llega al modelo. Consulta SECURITY.md para conocer el modelo de confianza, cómo se maneja la inyección indirecta de prompts y cómo reportar una vulnerabilidad.

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

Agradecimientos

Ollama por el runtime local de LLM
Model Context Protocol por la especificación y los ejemplos
any-llm por la interfaz única para múltiples proveedores de LLM
Rich por la interfaz de usuario de terminal
Typer por la experiencia moderna de CLI
Prompt Toolkit por la interfaz de línea de comandos interactiva
uv por el gestor de paquetes de Python ultrarrápido y la gestión de entornos virtuales
Asciinema por la grabación de demostraciones

Hecho con ❤️ por jonigl

MCP Client for Ollama

Documentación

MCP Client for Ollama (ollmcp)

Tabla de Contenidos

Descripción General

Características

Requisitos

Inicio Rápido

Opciones de Instalación

Solución de Problemas

Could not find a version that satisfies the requirement ollmcp (from versions: none)

error: externally-managed-environment (PEP 668)

Gestión de Servidores MCP mediante CLI

Opciones de mcp add

Ámbitos

Argumentos de línea de comandos

Configuración del servidor MCP:

Configuración del proveedor de inferencia:

Opciones generales:

Registro del servidor MCP:

Proveedores de inferencia compatibles

Orden de resolución de la clave API

Ejemplos de uso

Cómo funcionan las llamadas a herramientas

Modo Agente

Cuando se alcanza el límite de bucle

Demo rápida del Modo Agente:

Comandos Interactivos

Herramientas MCP

Prompts MCP

Características

Cómo Usar Prompts MCP

Recursos MCP

Características

Cómo Usar Recursos MCP

Modos de visualización de respuestas

Modo de entrada

Selección de modelo

Configuración avanzada del modelo

Mensaje del sistema

Parámetros clave

Comandos

Ejemplos de configuración

Modo de pensamiento y esfuerzo de razonamiento

Recarga de servidores para desarrollo

Ejecución de herramientas con intervención humana (HIL)

Pantalla de confirmación HIL

Opciones de confirmación HIL

Configuración de intervención humana (HIL)

Métricas de rendimiento

Configuración de métricas de rendimiento

Gestión del historial

Comandos del historial

Funciones de autocompletado y prompt

Autocompletado de shell Typer

Autocompletado estilo FZF

Autocompletado de prompts MCP

Prompt contextual

Gestión de configuración

Perfiles por proveedor

Formato de configuración del servidor

Consejos: dónde colocar las configuraciones del servidor MCP y un ejemplo funcional

Demo

Rutas de endpoint MCP comunes

Modelos compatibles

Modelos Ollama Cloud

Patrocinadores

Atlas Cloud

Conviértete en patrocinador

¿Dónde puedo encontrar más servidores MCP?

Proyectos relacionados

Seguridad

Licencia

Agradecimientos

`Could not find a version that satisfies the requirement ollmcp (from versions: none)`

`error: externally-managed-environment` (PEP 668)