Ollama MCP Server

---

✨ Características

• ☁️ Soporte de Ollama Cloud - Integración completa con la plataforma en la nube de Ollama
• 🔧 14 herramientas integrales - Acceso completo a la funcionalidad del SDK de Ollama
• 🔄 Arquitectura de intercambio en caliente - Descubrimiento automático de herramientas sin configuración
• 🎯 Seguridad de tipos - Construido con TypeScript y validación Zod
• 📊 Alta cobertura de pruebas - Más del 96% de cobertura con un conjunto de pruebas completo
• 🚀 Cero dependencias - Huella mínima, máximo rendimiento
• 🔌 Integración directa - Funciona con Claude Desktop, Cline y otros clientes MCP
• 🌐 Búsqueda web y fetch - Búsqueda web en tiempo real y extracción de contenido mediante Ollama Cloud
• 🔀 Modo híbrido - Usa modelos locales y en la nube sin problemas en un solo servidor

💡 Mejora tu experiencia con Ollama usando Claude Code y Desktop

El paquete completo: Herramientas + Conocimiento

Este servidor MCP le da a Claude las herramientas para interactuar con Ollama, pero obtendrás aún más valor instalando también la Ollama Skill del Skillsforge Marketplace:

• 🚗 Este MCP = El coche - Todas las herramientas y capacidades
• 🎓 Ollama Skill = Clases de conducción - Conocimiento experto sobre cómo usarlas de manera efectiva

La Ollama Skill enseña a Claude:

• Mejores prácticas para la selección y configuración de modelos
• Estrategias óptimas de prompting para diferentes modelos de Ollama
• Cuándo usar chat vs generate, embeddings y otras herramientas
• Optimización del rendimiento y resolución de problemas
• Funciones avanzadas como llamadas a herramientas y soporte de funciones

Instala ambos para la experiencia completa:

1. ✅ Este servidor MCP (herramientas)
2. ✅ Ollama Skill (conocimiento experto)

Resultado: Claude no solo tiene el coche, ¡sabe cómo conducirlo! 🏎️

📦 Instalación

Inicio rápido con Claude Desktop

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"]
    }
  }
}

Instalación global

npm install -g ollama-mcp

Para Cline (VS Code)

Añade a tu configuración MCP de Cline (cline_mcp_settings.json):

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"]
    }
  }
}

🛠️ Herramientas disponibles

Gestión de modelos

Herramienta	Descripción
ollama_list	Lista todos los modelos locales disponibles
ollama_show	Obtén información detallada sobre un modelo específico
ollama_pull	Descarga modelos de la biblioteca de Ollama
ollama_push	Sube modelos a la biblioteca de Ollama
ollama_copy	Crea una copia de un modelo existente
ollama_delete	Elimina modelos del almacenamiento local
ollama_create	Crea modelos personalizados a partir de Modelfile

Operaciones con modelos

Herramienta	Descripción
ollama_ps	Lista los modelos actualmente en ejecución
ollama_generate	Genera completaciones de texto
ollama_chat	Chat interactivo con modelos (soporta herramientas/funciones)
ollama_embed	Genera embeddings para texto

Herramientas web (Ollama Cloud)

Herramienta	Descripción
ollama_web_search	Busca en la web con límites de resultados personalizables (requiere OLLAMA_API_KEY)
ollama_web_fetch	Obtiene y analiza el contenido de páginas web (requiere OLLAMA_API_KEY)

Nota: Las herramientas web requieren una clave API de Ollama Cloud. Se conectan a https://ollama.com/api para operaciones de búsqueda web y fetch.

⚙️ Configuración

Variables de entorno

Variable	Valor predeterminado	Descripción
OLLAMA_HOST	http://127.0.0.1:11434	Endpoint del servidor de Ollama (usa https://ollama.com para la nube)
OLLAMA_API_KEY	-	Clave API para Ollama Cloud (requerida para herramientas web y modelos en la nube)

Host de Ollama personalizado

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"],
      "env": {
        "OLLAMA_HOST": "http://localhost:11434"
      }
    }
  }
}

Configuración de Ollama Cloud

Para usar la plataforma en la nube de Ollama con capacidades de búsqueda web y fetch:

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"],
      "env": {
        "OLLAMA_HOST": "https://ollama.com",
        "OLLAMA_API_KEY": "your-ollama-cloud-api-key"
      }
    }
  }
}

Características de la nube:

• ☁️ Accede a modelos alojados en la nube
• 🔍 Búsqueda web con ollama_web_search (requiere clave API)
• 📄 Fetch web con ollama_web_fetch (requiere clave API)
• 🚀 Inferencia más rápida en infraestructura en la nube

Obtén tu clave API: Visita ollama.com para registrarte y obtener tu clave API.

Modo híbrido (Local + Nube)

Puedes usar modelos locales y en la nube apuntando a tu instancia local de Ollama mientras proporcionas una clave API:

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"],
      "env": {
        "OLLAMA_HOST": "http://127.0.0.1:11434",
        "OLLAMA_API_KEY": "your-ollama-cloud-api-key"
      }
    }
  }
}

Esta configuración:

• ✅ Ejecuta modelos locales desde tu instancia de Ollama
• ✅ Habilita herramientas de búsqueda web y fetch solo en la nube
• ✅ Lo mejor de ambos mundos: privacidad + conectividad web

🔄 Comportamiento de reintentos

El servidor MCP incluye lógica de reintentos inteligente para manejar fallos transitorios al comunicarse con las APIs de Ollama:

Estrategia automática de reintentos

Herramientas web (ollama_web_search y ollama_web_fetch):

• Reintenta automáticamente en errores de límite de velocidad (HTTP 429)
• Máximo de 3 intentos de reintento (4 solicitudes totales incluyendo la inicial)
• Tiempo de espera de solicitud: 30 segundos por solicitud (evita conexiones colgadas)
• Respeta el encabezado Retry-After cuando lo proporciona la API
• Recurre a retroceso exponencial con jitter cuando Retry-After no está presente

Soporte del encabezado Retry-After

El servidor maneja inteligentemente el encabezado HTTP estándar Retry-After en dos formatos:

1. Formato de segundos de retraso:

Retry-After: 60

Espera exactamente 60 segundos antes de reintentar.

2. Formato de fecha HTTP:

Retry-After: Wed, 21 Oct 2025 07:28:00 GMT

Calcula el retraso hasta la marca de tiempo especificada.

Retroceso exponencial

Cuando Retry-After no se proporciona o no es válido:

• Retraso inicial: 1 segundo (predeterminado)
• Retraso máximo: 10 segundos (predeterminado, configurable)
• Estrategia: Retroceso exponencial con jitter completo
• Fórmula: random(0, min(initialDelay × 2^attempt, maxDelay))

Ejemplo de retrasos de reintento:

• 1er reintento: 0-1 segundos
• 2º reintento: 0-2 segundos
• 3er reintento: 0-4 segundos (limitado a 0-10 s máximo)

Manejo de errores

Errores con reintento (fallos transitorios):

• HTTP 429 (Demasiadas solicitudes) - limitación de velocidad
• HTTP 500 (Error interno del servidor) - problemas transitorios del servidor
• HTTP 502 (Bad Gateway) - la puerta de enlace/proxy recibió una respuesta no válida
• HTTP 503 (Servicio no disponible) - el servidor no puede manejar temporalmente la solicitud
• HTTP 504 (Tiempo de espera de la puerta de enlace) - la puerta de enlace/proxy no recibió una respuesta oportuna

Errores sin reintento (fallos permanentes):

• Tiempos de espera de solicitud (se excedió el límite de 30 segundos)
• Tiempos de espera de red (sin código de estado)
• Errores de cancelación/aborto
• Errores HTTP 4xx (excepto 429) - errores de cliente que requieren cambios
• Otros errores HTTP 5xx (501, 505, 506, 508, etc.) - problemas de configuración/implementación

El mecanismo de reintentos garantiza un manejo robusto de problemas temporales de la API, respetando las pautas de reintento proporcionadas por el servidor y evitando tasas de solicitud excesivas. Los errores 5xx transitorios (500, 502, 503, 504) son seguros de reintentar para las operaciones POST idempotentes utilizadas por ollama_web_search y ollama_web_fetch. Las solicitudes individuales expiran después de 30 segundos para evitar conexiones colgadas indefinidamente.

🎯 Ejemplos de uso

Chat con un modelo

// MCP clients can invoke:
{
  "tool": "ollama_chat",
  "arguments": {
    "model": "llama3.2:latest",
    "messages": [
      { "role": "user", "content": "Explain quantum computing" }
    ]
  }
}

Generar embeddings

{
  "tool": "ollama_embed",
  "arguments": {
    "model": "nomic-embed-text",
    "input": ["Hello world", "Embeddings are great"]
  }
}

Búsqueda web

{
  "tool": "ollama_web_search",
  "arguments": {
    "query": "latest AI developments",
    "max_results": 5
  }
}

🏗️ Arquitectura

Este servidor utiliza un patrón de autocargador de intercambio en caliente:

src/
├── index.ts          # Entry point (27 lines)
├── server.ts         # MCP server creation
├── autoloader.ts     # Dynamic tool discovery
└── tools/            # Tool implementations
    ├── chat.ts       # Each exports toolDefinition
    ├── generate.ts
    └── ...

Beneficios clave:

• Añade nuevas herramientas colocando archivos en src/tools/
• No se requieren cambios en el código del servidor
• Cada herramienta es comprobable de forma independiente
• 100% de cobertura de funciones en todas las herramientas

🧪 Desarrollo

Requisitos previos

• Node.js v16+
• npm o pnpm
• Ollama ejecutándose localmente

Configuración

# Clone repository
git clone https://github.com/rawveg/ollama-mcp.git
cd ollama-mcp

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Cobertura de pruebas

Statements   : 96.37%
Branches     : 84.82%
Functions    : 100%
Lines        : 96.37%

Añadir una nueva herramienta

1. Crea src/tools/your-tool.ts:

import { ToolDefinition } from '../autoloader.js';
import { Ollama } from 'ollama';
import { ResponseFormat } from '../types.js';

export const toolDefinition: ToolDefinition = {
  name: 'ollama_your_tool',
  description: 'Your tool description',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string' }
    },
    required: ['param']
  },
  handler: async (ollama, args, format) => {
    // Implementation
    return 'result';
  }
};

2. Crea pruebas en tests/tools/your-tool.test.ts
3. ¡Listo! El autocargador la descubre automáticamente.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor, sigue estas pautas:

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad (git checkout -b feature/amazing-feature)
3. Escribe pruebas - Mantenemos más del 96% de cobertura
4. Haz commits con mensajes claros (git commit -m 'Add amazing feature')
5. Sube a tu rama (git push origin feature/amazing-feature)
6. Abre una Pull Request

Estándares de calidad del código

• Todas las herramientas nuevas deben exportar toolDefinition
• Mantén una cobertura de pruebas ≥80%
• Sigue los patrones TypeScript existentes
• Usa esquemas Zod para la validación de entrada

📄 Licencia

Este proyecto está licenciado bajo la GNU Affero General Public License v3.0 (AGPL-3.0).

Consulta LICENSE para más detalles.

🔗 Proyectos relacionados

• Skillsforge Marketplace - Habilidades de Claude Code, incluida la Ollama Skill
• Ollama - Ponte en marcha con modelos de lenguaje grandes localmente
• Model Context Protocol - Estándar abierto para la integración de asistentes de IA
• Claude Desktop - La aplicación de escritorio de Anthropic
• Cline - Asistente de IA para VS Code

🙏 Agradecimientos

Construido con:

• Ollama SDK - Biblioteca oficial de JavaScript de Ollama
• MCP SDK - SDK del Model Context Protocol
• Zod - Validación de esquemas con TypeScript en primer lugar

---