Dale herramientas reales a un modelo local: Ollama más MCP

Este es el dato que la mayoría de las guías entierran. Ollama es un servidor de modelos. Su API acepta una lista de herramientas y devuelve llamadas a herramientas, y la documentación oficial muestra ese ciclo en detalle. Iniciar un servidor MCP, leer su lista de herramientas, ejecutar la llamada que pidió el modelo y traer de vuelta el resultado es un segundo trabajo, y Ollama no hace ese trabajo. Necesitas un cliente MCP entre el modelo y los servidores. Este tutorial instala ese cliente, conecta un servidor seguro y termina con un modelo local que lee y escribe archivos reales en tu propia computadora, sin ninguna cuenta en la nube en el ciclo.

Lo que vas a construir o aprender

Terminarás con un chat de terminal donde un modelo local puede usar el servidor oficial de sistema de archivos MCP en una carpeta de prueba que tú elijas. El modelo listará esa carpeta, creará un archivo dentro de ella cuando apruebes la llamada y leerá el archivo de vuelta. El patrón se repite luego para cualquier otro servidor MCP que agregues, porque el cliente, no el modelo, es dueño de la lista de servidores.

La ruta aquí usa ollmcp, el proyecto MCP Client for Ollama, porque habla con Ollama en su API nativa y se queda en la terminal. Los agentes de programación lanzados mediante Ollama, como las integraciones detrás de ollama launch, también son clientes MCP y siguen la misma forma. El cliente cambia. La división del trabajo no.

La mascota llama de Ollama con casco de obra sosteniendo un martillo junto a una caja de herramientas abierta, del anuncio de soporte de herramientas de Ollama

Antes de empezar

Empieza con una carpeta de prueba, nunca con tu carpeta personal ni con la raíz de una unidad. El servidor de sistema de archivos puede leer y escribir cada ruta que le entregues, y un modelo que malinterprete una instrucción puede hacer daño real dentro de esas rutas. El aviso de aprobación en ollmcp está activado por defecto y muestra cada llamada a herramienta antes de que se ejecute. Déjalo activado durante todo este tutorial.

Paso 1: Instala Ollama y confirma que el servidor responde

Acción: instala Ollama desde su sitio oficial, o usa el script en Linux y macOS. Luego confirma que el servidor local responde.

curl -fsSL https://ollama.com/install.sh | sh
ollama --version
curl http://localhost:11434/

Resultado esperado: el comando de versión imprime tu versión de Ollama, y la llamada final responde con la línea de texto plano Ollama is running. En Windows y macOS, abre la aplicación de Ollama una vez si el servidor no responde, ya que la aplicación inicia el servidor en segundo plano. Nada más en este tutorial funciona mientras esa dirección permanezca en silencio.

Paso 2: Descarga un modelo que pueda llamar herramientas

Acción: descarga un modelo con soporte de herramientas. El proyecto ollmcp enumera las líneas qwen2.5 y qwen3 y llama3.1 y llama3.2 entre los modelos que funcionan bien con el uso de herramientas, y la documentación de llamadas a herramientas de Ollama construye sus ejemplos sobre qwen3. Empieza con el tamaño 8B.

ollama pull qwen3:8b
ollama list

Resultado esperado: ollama list muestra qwen3:8b en disco. Un modelo sin soporte de herramientas seguirá conversando dentro del cliente y nunca llamará a una herramienta, que es la causa más común de una instalación que parece terminada y no hace nada. Si cambias de modelo más adelante, revisa primero la página del modelo para confirmar el soporte de herramientas.

Paso 3: Eleva el contexto antes de que lleguen las listas de herramientas

Acción: reinicia Ollama con un contexto mayor. Las listas de herramientas consumen contexto rápido. El propio Ollama señala que una ventana de contexto de 32k o superior mejora el rendimiento de las llamadas a herramientas, y una ventana predeterminada pequeña puede no dejar espacio para las definiciones de herramientas más tu conversación. Detén primero el servidor en ejecución y luego inícialo con el ajuste en su lugar.

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

Resultado esperado: Ollama se inicia y sirve como de costumbre, ahora con espacio para la lista de herramientas del sistema de archivos y una conversación funcional. El uso de memoria aumenta con el contexto, así que este es un intercambio que haces a propósito. Ejecuta este servidor en su propia ventana de terminal y déjala abierta mientras avanzas por el resto de los pasos.

Paso 4: Instala el cliente MCP

Acción: instala ollmcp con pip, o ejecútalo en un paso con la herramienta uv si ya la usas.

pip install ollmcp
ollmcp --help

Resultado esperado: el texto de ayuda imprime las opciones del cliente, incluidas --mcp-server, --servers-json, --model y --host. El host predeterminado es http://localhost:11434, que coincide con el Paso 1, así que no se necesita trabajo de direcciones para una instalación local.

Paso 5: Escribe la configuración del servidor

Acción: crea una carpeta de prueba y un archivo de configuración que entregue esa única carpeta al servidor oficial de sistema de archivos. Reemplaza la ruta de usuario de ejemplo con tu propia ruta absoluta, y mantenla apuntando solo a la carpeta de prueba.

mkdir -p ~/ollama-mcp/playground

Guarda esto como servers.json dentro de la carpeta ~/ollama-mcp:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/yourname/ollama-mcp/playground"]
    }
  }
}

Resultado esperado: el archivo nombra un servidor, iniciado por npx, con una raíz permitida. El servidor de sistema de archivos rechaza rutas fuera de las raíces en su lista de argumentos, que es la barrera que hace segura la prueba. En Windows, usa la ruta completa de Windows para la carpeta playground en el mismo espacio de argumento.

Paso 6: Inicia el cliente y revisa las herramientas cargadas

Acción: inicia ollmcp con tu archivo de configuración y tu modelo descargado.

ollmcp --servers-json ~/ollama-mcp/servers.json --model qwen3:8b

Resultado esperado: el cliente se conecta a Ollama, inicia el servidor de sistema de archivos y abre su pantalla de chat. Escribe tools y presiona Enter. La lista de herramientas debería mostrar las herramientas del sistema de archivos, entre ellas herramientas para listar un directorio, leer un archivo y escribir un archivo. Si la lista está vacía, el servidor no se inició, y el Paso 5 es donde mirar primero.

Paso 7: Dale al modelo una tarea real

Acción: pide trabajo que solo una herramienta puede hacer, en palabras sencillas.

List the files in the playground folder. Then create a file called hello.txt in that folder with one sentence: the local model was here. Then read hello.txt back and tell me what it says.

Resultado esperado: antes de que se ejecute la escritura, el aviso de aprobación muestra el nombre de la herramienta y sus argumentos. Léelos, confirma que la ruta está dentro de la carpeta playground y aprueba. El modelo debería informar primero una carpeta vacía o casi vacía, crear el archivo y citar tu frase de vuelta desde la lectura. Esa cita vino del disco, no de la memoria del chat, y esa diferencia es todo el sentido de la instalación.

Verificación

Abre una segunda terminal y revisa el archivo tú mismo, sin preguntarle al modelo.

ls ~/ollama-mcp/playground
cat ~/ollama-mcp/playground/hello.txt

El listado muestra hello.txt, y la salida muestra tu frase exactamente como se escribió. Dentro del cliente, escribe tools una vez más y confirma que las herramientas del sistema de archivos siguen como activadas. Si el archivo existe en disco y el cliente sigue listando las herramientas, el ciclo funciona de extremo a extremo: instrucción, llamada a herramienta, aprobación, servidor, resultado, respuesta.

Solución de problemas

Problema	Causa probable	Solución
El modelo conversa pero nunca llama a una herramienta	El modelo descargado carece de soporte de herramientas, o el contexto es demasiado pequeño para la lista de herramientas	Descarga `qwen3:8b`, reinicia Ollama con el contexto del Paso 3 e inicia el cliente de nuevo
El cliente se abre sin herramientas listadas	El servidor de sistema de archivos no se pudo iniciar	Prueba el servidor por su cuenta con `npx -y @modelcontextprotocol/server-filesystem` más tu ruta playground, y corrige la ruta o la instalación de Node.js que informe
Conexión rechazada en `localhost:11434`	Ollama no está en ejecución	Abre la aplicación de Ollama, o ejecuta `ollama serve`, y luego inicia el cliente de nuevo
El modelo dice que no puede llegar a una carpeta	Esa carpeta está fuera de la raíz permitida en `servers.json`	Agrega la ruta absoluta correcta a los argumentos del servidor, guarda el archivo y escribe `reload-servers` dentro del cliente
Una llamada a herramienta que esperabas nunca pidió aprobación y nunca se ejecutó	La herramienta está desactivada en la lista de herramientas del cliente	Escribe `tools`, activa la herramienta o su servidor, guarda y repite la solicitud
El modelo inventa el contenido de archivos en lugar de leer	Respondió sin una llamada a herramienta en ese turno	Pregunta de nuevo y nombra la acción de la herramienta en la instrucción, y observa el aviso de aprobación como prueba de que la llamada salió

Próximos pasos

Agrega un segundo servidor al mismo archivo servers.json y el cliente ofrecerá ambos conjuntos de herramientas en un chat. La colección oficial de servidores MCP es el estante seguro donde buscar, y el patrón del sistema de archivos en el Paso 5 cubre la mayoría de los servidores stdio: un comando, sus argumentos y un bloque env donde se necesite una clave, escrita como marcador en cualquier cosa que compartas. Guarda una configuración que funcione con el comando save-config dentro del cliente para que un ollmcp simple reabra la misma instalación.

Cuando el trabajo pase del chat al código, los mismos servidores te siguen. Los agentes iniciados mediante ollama launch, como OpenCode y Claude Code, leen su propia configuración MCP y manejan el modelo local de la misma manera que ollmcp lo hace aquí. Aprende el ciclo primero en la terminal, donde cada llamada pide tu permiso. Luego entrégale herramientas más grandes con los ojos abiertos.

Comandos y comportamiento verificados contra la documentación de llamadas a herramientas de Ollama, la nota de Ollama sobre llamadas a herramientas en streaming y tamaño de contexto, la documentación del proyecto ollmcp y el formato de configuración del servidor de sistema de archivos MCP, octubre de 2026. Este procedimiento se verificó contra esos documentos; ejecútalo primero en una carpeta de prueba, como está escrito.

Fuentes

Ilustración: Ollama