ikarius6/ollama-mcp-server

Ollama MCP Server - by Mr.Jack

Un servidor MCP (Model Context Protocol) para integrar modelos Ollama con aplicaciones que soportan el protocolo MCP, como Claude Desktop o Windsurf.

📋 Características

• Listar modelos: Lista todos los modelos Ollama disponibles localmente
• Generación de texto: Genera texto usando modelos Ollama
• Chat: Mantiene conversaciones con modelos Ollama
• Descargar modelos: Descarga modelos desde el registro de Ollama
• Soporte para streaming: Maneja respuestas en streaming para modelos pesados
• Timeouts configurables: Configura timeouts para modelos que tardan en responder

🚀 Requisitos Previos

• Node.js v18 o superior
• Ollama instalado y en ejecución
  • Descarga desde: https://ollama.ai
  • Verifica que esté corriendo con: ollama list

📦 Instalación

1. Clona o descarga este repositorio

2. Instala las dependencias:

   npm install
   

3. Compila el proyecto:

   npm run build
   

4. Instala globalmente (opcional pero recomendado):

   npm link
   

   Esto crea un enlace simbólico global al comando ollama-mcp-server, permitiendo ejecutarlo desde cualquier ubicación sin especificar la ruta completa.

🛠️ Uso

Modo Desarrollo

Para ejecutar en modo desarrollo con recarga automática:

npm run dev

Modo Producción

Después de compilar, el servidor se puede ejecutar directamente:

node build/ollama-mcp-server.js

Integración con Claude Desktop o Windsurf

Para usar este servidor MCP con Claude Desktop o Windsurf, agrega la siguiente configuración a tu archivo de configuración:

Windows: %APPDATA%\Claude\claude_desktop_config.json o %USERPROFILE%\.codeium\windsurf\mcp_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json o ~/Library/Application Support/Windsurf/config.json

Linux: ~/.config/Claude/claude_desktop_config.json o ~/.config/Windsurf/config.json

Opción 1: Usando npm link (Recomendado)

Si instalaste globalmente con npm link:

{
  "mcpServers": {
    "ollama": {
      "command": "ollama-mcp-server",
      "args": [],
      "env": {
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_TIMEOUT": "1200000"
      },
      "disabled": false
    }
  }
}

Opción 2: Usando ruta absoluta

Si prefieres no usar npm link:

{
  "mcpServers": {
    "ollama": {
      "command": "node",
      "args": ["d:\\Aplicaciones\\ollama-mcp-server\\build\\ollama-mcp-server.js"],
      "env": {
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_TIMEOUT": "1200000"
      }
    }
  }
}

Nota: En la Opción 2, ajusta la ruta absoluta en args según donde hayas instalado el proyecto.

⚙️ Variables de Entorno

🔧 Herramientas Disponibles

El servidor MCP expone las siguientes herramientas:

1. ollama_list_models

Lista todos los modelos Ollama disponibles en tu sistema.

Sin parámetros requeridos

2. ollama_generate

Genera texto usando un modelo Ollama.

Parámetros:

• model (string, requerido): Nombre del modelo (ej: 'llama3', 'mistral')
• prompt (string, requerido): El prompt a enviar al modelo
• temperature (number, opcional): Temperatura de generación (0.0 a 2.0, por defecto: 0.8)
• top_p (number, opcional): Top P para nucleus sampling
• top_k (number, opcional): Top K para sampling

3. ollama_chat

Mantiene una conversación con un modelo Ollama.

Parámetros:

• model (string, requerido): Nombre del modelo
• messages (array, requerido): Array de objetos con 'role' y 'content'
  • role: 'system', 'user', o 'assistant'
  • content: El contenido del mensaje
• temperature (number, opcional): Temperatura de generación (por defecto: 0.8)

4. ollama_pull_model

Descarga un modelo desde el registro de Ollama.

Parámetros:

• model (string, requerido): Nombre del modelo a descargar (ej: 'llama3', 'mistral')

📝 Ejemplos de Uso

Una vez configurado en Claude Desktop o Windsurf, puedes usar comandos como:

• "Lista todos los modelos Ollama disponibles"
• "Genera un poema usando el modelo llama3"
• "Chatea con el modelo mistral sobre programación en Python"
• "Descarga el modelo codellama"
• "Usando @mcp.ollama:llama3 genera un poema"

🐛 Solución de Problemas

El servidor no se conecta a Ollama

• Verifica que Ollama esté corriendo: ollama list
• Comprueba que el puerto sea correcto (por defecto: 11434)
• Revisa la variable de entorno OLLAMA_HOST

Timeout en modelos grandes

• Aumenta el valor de OLLAMA_TIMEOUT en la configuración
• Algunos modelos pueden tardar varios minutos en responder

Error "Module not found"

• Asegúrate de haber ejecutado npm install
• Verifica que ejecutaste npm run build antes de usar el servidor

📄 Licencia

ISC

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue o pull request para sugerencias o mejoras.