Ollama MCP Server

Integra instancias locales de LLM de Ollama con aplicaciones compatibles con MCP.

GitHub
6
Prueba este MCPPatrocinado

Documentación

ollama-MCP-server

Servidor de Protocolo de Contexto de Modelo (MCP) que se comunica con Ollama

Resumen

Este servidor MCP permite una integración fluida entre instancias locales de LLM de Ollama y aplicaciones compatibles con MCP, proporcionando descomposición avanzada de tareas, evaluación y gestión de flujos de trabajo.

Características principales:

  • Descomposición de tareas complejas
  • Evaluación y validación de resultados
  • Gestión y ejecución de modelos de Ollama
  • Comunicación estandarizada mediante el protocolo MCP
  • Manejo avanzado de errores y mensajes de error detallados
  • Optimización del rendimiento (agrupación de conexiones, caché LRU)

Componentes

Recursos

El servidor implementa los siguientes recursos:

  • task:// - Esquema de URI para acceder a tareas individuales
  • result:// - Esquema de URI para acceder a resultados de evaluación
  • model:// - Esquema de URI para acceder a los modelos de Ollama disponibles

Cada recurso está configurado con los metadatos y tipos MIME apropiados para una interacción óptima con el LLM.

Relación entre prompts y herramientas

En el servidor MCP, los prompts y las herramientas están estrechamente relacionados, pero tienen roles diferentes.

  • Prompts: Actúan como un esquema que proporciona al LLM una forma específica de pensar o una estructura.
  • Herramientas: Actúan como manejadores que ejecutan acciones reales.

Cada herramienta requiere un esquema (prompt) correspondiente, lo que permite una coordinación efectiva entre la capacidad de razonamiento del LLM y las funcionalidades reales del sistema.

Prompts

El servidor proporciona varios prompts especializados:

  • decompose-task - Descompone tareas complejas en subtareas manejables

    • Recibe la descripción de la tarea y un parámetro opcional de nivel de granularidad
    • Devuelve un desglose estructurado que incluye dependencias y complejidad estimada

  • evaluate-result - Analiza los resultados de una tarea según criterios específicos

    • Recibe el contenido del resultado y los parámetros de evaluación
    • Devuelve una evaluación detallada con puntuación y sugerencias de mejora

Herramientas

El servidor implementa varias herramientas potentes:

  • add-task

    • Parámetros obligatorios: name (cadena), description (cadena)
    • Parámetros opcionales: priority (número), deadline (cadena), tags (matriz)
    • Crea una nueva tarea en el sistema y devuelve su identificador
    • Esquema correspondiente: esquema de validación de datos para la creación de tareas

  • decompose-task

    • Parámetros obligatorios: task_id (cadena), granularity (cadena: "high"|"medium"|"low")
    • Parámetros opcionales: max_subtasks (número)
    • Utiliza Ollama para descomponer tareas complejas en subtareas manejables
    • Esquema correspondiente: el prompt decompose-task mencionado anteriormente

  • evaluate-result

    • Parámetros obligatorios: result_id (cadena), criteria (objeto)
    • Parámetros opcionales: detailed (booleano)
    • Evalúa resultados según criterios específicos y proporciona retroalimentación
    • Esquema correspondiente: el prompt evaluate-result mencionado anteriormente

  • run-model

    • Parámetros obligatorios: model (cadena), prompt (cadena)
    • Parámetros opcionales: temperature (número), max_tokens (número)
    • Ejecuta un modelo de Ollama con los parámetros especificados
    • Esquema correspondiente: esquema de validación de parámetros de ejecución del modelo de Ollama

Nuevas características y mejoras

Manejo ampliado de errores

El servidor proporciona mensajes de error más detallados y estructurados, lo que permite a las aplicaciones cliente manejar los errores de manera más efectiva. Ejemplo de respuesta de error:

{
  "error": {
    "message": "Task not found: task-123",
    "status_code": 404,
    "details": {
      "provided_id": "task-123"
    }
  }
}

Optimización del rendimiento

  • Agrupación de conexiones: El uso de un grupo de conexiones HTTP compartido mejora el rendimiento de las solicitudes y reduce el uso de recursos.
  • Caché LRU: Al almacenar en caché las respuestas a solicitudes idénticas o similares, se reducen los tiempos de respuesta y se alivia la carga del servidor de Ollama.

Estos ajustes se pueden configurar en config.py:

# パフォーマンス関連設定
cache_size: int = 100                 # キャッシュに保存する最大エントリ数
max_connections: int = 10             # 同時接続の最大数
max_connections_per_host: int = 10    # ホストごとの最大接続数
request_timeout: int = 60             # リクエストタイムアウト（秒）

Función de especificación de modelos

Resumen

Ollama-MCP-Server ofrece una función flexible que permite especificar modelos de Ollama de múltiples maneras.

Prioridad de especificación de modelos

Los modelos se especifican según el siguiente orden de prioridad:

  1. Parámetros en la llamada a la herramienta (parámetro model)
  2. Sección env del archivo de configuración MCP
  3. Variables de entorno (OLLAMA_DEFAULT_MODEL)
  4. Valor predeterminado (llama3)

Especificación de modelos mediante el archivo de configuración MCP

Cuando se utiliza con clientes como Claude Desktop, se puede especificar el modelo mediante el archivo de configuración MCP:

{
  "mcpServers": {
    "ollama-MCP-server": {
      "command": "python",
      "args": [
        "-m",
        "ollama_mcp_server"
      ],
      "env": [
        {"model": "llama3:latest"}
      ]
    }
  }
}

Verificación de modelos disponibles

Al iniciar el servidor, se verifica si el modelo configurado existe. Si no se encuentra el modelo, se emite un registro de advertencia. Además, la herramienta run-model devuelve la lista de modelos disponibles, lo que permite al usuario seleccionar un modelo válido.

Mejoras en el manejo de errores

Si el modelo especificado no existe o se produce un error de comunicación, se proporcionan mensajes de error detallados. Los mensajes de error incluyen la lista de modelos disponibles, lo que permite al usuario resolver el problema rápidamente.

Pruebas

El proyecto incluye un conjunto completo de pruebas:

  • Pruebas unitarias: Prueban la funcionalidad de componentes individuales
  • Pruebas de integración: Prueban flujos de trabajo de extremo a extremo

Para ejecutar las pruebas:

# すべてのテストを実行
python -m unittest discover

# 特定のテストを実行
python -m unittest tests.test_integration

Configuración

Variables de entorno

OLLAMA_HOST=http://localhost:11434
DEFAULT_MODEL=llama3
LOG_LEVEL=info

Configuración de Ollama

Asegúrese de que Ollama esté instalado y ejecutándose con los modelos adecuados:

# Ollamaをインストール（まだインストールされていない場合）
curl -fsSL https://ollama.com/install.sh | sh

# 推奨モデルをダウンロード
ollama pull llama3
ollama pull mistral
ollama pull qwen2

Inicio rápido

Instalación

pip install ollama-mcp-server

Configuración de Claude Desktop

MacOS

Ruta: ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

Ruta: %APPDATA%/Claude/claude_desktop_config.json

Configuración para servidores de desarrollo/no publicados 
"mcpServers": {
  "ollama-MCP-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/ollama-MCP-server",
      "run",
      "ollama-MCP-server"
    ],
    "ENV":["model":"deepseek:r14B"]
  }
}
Configuración para servidores publicados 
"mcpServers": {
  "ollama-MCP-server": {
    "command": "uvx",
    "args": [
      "ollama-MCP-server"
    ]
  }
}

Ejemplos de uso

Descomposición de tareas

Para descomponer una tarea compleja en subtareas manejables:

result = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "decompose-task",
    "arguments": {
        "task_id": "task://123",
        "granularity": "medium",
        "max_subtasks": 5
    }
})

Evaluación de resultados

Para evaluar un resultado según criterios específicos:

evaluation = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "evaluate-result",
    "arguments": {
        "result_id": "result://456",
        "criteria": {
            "accuracy": 0.4,
            "completeness": 0.3,
            "clarity": 0.3
        },
        "detailed": true
    }
})

Ejecución de modelos de Ollama

Para ejecutar consultas directamente contra un modelo de Ollama:

response = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "run-model",
    "arguments": {
        "model": "llama3",
        "prompt": "量子コンピューティングを簡単な言葉で説明してください",
        "temperature": 0.7
    }
})

Desarrollo

Configuración del proyecto

  1. Clonar el repositorio:
git clone https://github.com/yourusername/ollama-MCP-server.git
cd ollama-MCP-server
  1. Crear y activar un entorno virtual:
python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate
  1. Instalar las dependencias de desarrollo:
uv sync --dev --all-extras

Desarrollo local

El proyecto incluye scripts de desarrollo convenientes:

Ejecutar el servidor

./run_server.sh

Opciones:

  • --debug: Ejecutar en modo depuración (nivel de registro: DEBUG)
  • --log=LEVEL: Especificar el nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Ejecutar las pruebas

./run_tests.sh

Opciones:

  • --unit: Ejecutar solo pruebas unitarias
  • --integration: Ejecutar solo pruebas de integración
  • --all: Ejecutar todas las pruebas (predeterminado)
  • --verbose: Salida detallada de pruebas

Compilación y publicación

Para preparar el paquete para su distribución:

  1. Sincronizar dependencias y actualizar el archivo de bloqueo:
uv sync
  1. Compilar los distributivos del paquete:
uv build

Esto creará distributivos de código fuente y wheel en el directorio dist/.

  1. Publicar en PyPI:
uv publish

Nota: Debe configurar las credenciales de PyPI mediante variables de entorno o indicadores de línea de comandos:

  • Token: --token o UV_PUBLISH_TOKEN
  • O nombre de usuario/contraseña: --username/UV_PUBLISH_USERNAME y --password/UV_PUBLISH_PASSWORD

Depuración

Dado que el servidor MCP se ejecuta a través de stdio, la depuración puede ser difícil. Para una experiencia de depuración óptima, se recomienda encarecidamente el uso de MCP Inspector.

Para iniciar MCP Inspector con npm, ejecute el siguiente comando:

npx @modelcontextprotocol/inspector uv --directory /path/to/ollama-MCP-server run ollama-mcp-server

Al iniciarse, Inspector mostrará una URL a la que puede acceder en el navegador para comenzar a depurar.

Arquitectura

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar solicitudes de extracción.

  1. Haga un fork del repositorio
  2. Cree una rama de funcionalidad (git checkout -b feature/amazing-feature)
  3. Confirme sus cambios (git commit -m 'Add some amazing feature')
  4. Haga push a la rama (git push origin feature/amazing-feature)
  5. Abra una solicitud de extracción

Licencia

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

Agradecimientos

  • Al equipo de Model Context Protocol por proporcionar un excelente diseño de protocolo
  • Al proyecto Ollama por hacer accesible la ejecución local de LLM
  • A todos los contribuyentes de este proyecto