Servidor MCP Ollama-Omega

Un servidor MCP reforzado que conecta el ecosistema completo de Ollama (modelos locales y gigantes alojados en la nube) con cualquier IDE compatible con MCP. Sin scripts envolventes. Sin SDK inflado. Solo un archivo Python con dos dependencias.

PRINCIPIO DE DISEÑO: Ollama-Omega no abstrae Ollama. Expone la superficie completa de la API de Ollama a través de 6 herramientas validadas y con manejo de errores, sin pérdida de información.

Arquitectura

┌─────────────────────────────────────────────────────┐
│                    MCP Client (IDE)                  │
│         Claude Desktop / Antigravity / etc.          │
└──────────────────────┬──────────────────────────────┘
                       │ stdio (JSON-RPC 2.0)
┌──────────────────────▼──────────────────────────────┐
│              ollama_mcp_server.py                     │
│  ┌──────────┐ ┌──────────┐ ┌───────────────────┐    │
│  │ Validator│ │ Dispatch │ │ Singleton httpx   │    │
│  │ + Schema │→│ Router   │→│ AsyncClient       │    │
│  └──────────┘ └──────────┘ │ (no redirects)    │    │
│                             └─────────┬─────────┘    │
└───────────────────────────────────────┼──────────────┘
                                        │ HTTP
┌───────────────────────────────────────▼──────────────┐
│                  Ollama Daemon                        │
│    Local models (GPU) │ Cloud models (API proxy)      │
└───────────────────────────────────────────────────────┘

Herramientas (6)

Herramienta	Propósito
`ollama_health`	Comprobar la conectividad y listar los modelos cargados/en ejecución
`ollama_list_models`	Listar todos los modelos disponibles con tamaño, estado de carga y fecha de modificación
`ollama_chat`	Enviar una solicitud de chat con historial de mensajes y prompt del sistema
`ollama_generate`	Generar una respuesta para un prompt dado sin historial de chat
`ollama_show_model`	Mostrar información detallada sobre un modelo específico (licencia, parámetros)
`ollama_pull_model`	Descargar un modelo desde la biblioteca de Ollama

Auditoría de Refuerzo

#	Categoría	Mitigación
1	SSRF	Redirecciones deshabilitadas en el cliente httpx (`follow_redirects=False`)
2	Fuga de recursos	`AsyncClient` singleton: un pool de conexiones para toda la vida del servidor
3	Validación de entrada	Puerta `_validate_required()` en cada herramienta antes de cualquier llamada HTTP
4	Seguridad JSON	Envoltorio `_safe_json()`: nunca falla ante respuestas mal formadas
5	Registro estructurado	Toda la salida stderr a través del módulo `logging`, no `print()` sin procesar
6	Cargas útiles DRY	`_build_options()` centraliza el mapeo de temperatura/tokens
7	Sanitización de errores	Ayudante `_error()`: sin seguimientos de pila, sin filtración de internos al cliente

Inicio rápido

Requisitos

Python 3.11+
pip install mcp httpx

Configuración en Claude Desktop / Antigravity

{
  "mcpServers": {
    "ollama": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/ollama-mcp",
        "run",
        "python",
        "ollama_mcp_server.py"
      ],
      "env": {
        "PYTHONUTF8": "1",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_TIMEOUT": "300"
      }
    }
  }
}

Variables de entorno

Variable	Predeterminado	Descripción
`OLLAMA_HOST`	`http://localhost:11434`	URL del demonio Ollama
`OLLAMA_TIMEOUT`	`300`	Tiempo de espera de solicitud en segundos (largo para descargas de modelos grandes/inferencia en la nube)
`PYTHONUTF8`	—	Establecer en `1` para seguridad Unicode en Windows

Modelos en la nube

Ollama-Omega es agnóstico a la versión. Si su demonio Ollama expone modelos alojados en la nube (p. ej., qwen3.5:397b-cloud a través de un proxy API), son accesibles a través de las mismas 6 herramientas, sin necesidad de cambios de configuración.

Estructura de archivos

Ollama-Omega/
  ollama_mcp_server.py     # MCP server (~307 lines) — hardened, single-file
  pyproject.toml            # Package metadata, CLI entry, PyPI classifiers
  requirements.txt          # mcp>=1.0.0, httpx>=0.27.0
  glama.json                # Glama MCP directory registration
  LICENSE                   # MIT
  CHANGELOG.md              # Version history
  tests/
    test_server.py           # 48 tests — tools, dispatch, errors, SSRF, config
  examples/
    basic_usage.py           # Programmatic MCP client example
  docs/
    BUILD_SPEC.md            # Internal build specification

Pruebas

pip install pytest
python -m pytest tests/ -v

48 pruebas que cubren:

Definiciones de herramientas: validación de esquema, campos obligatorios, descripciones
Funciones auxiliares: constructor de opciones, validación, seguridad JSON, formato de errores
Despachador: las 6 rutas de herramientas con respuestas HTTP simuladas
Manejo de errores: conexión, tiempo de espera, estado HTTP, sanitización de excepciones
Configuración: valores predeterminados del entorno, mitigación de SSRF, identidad del servidor

Servidor complementario

Ollama-Omega es la capa de transporte para Omega Brain MCP: memoria episódica entre sesiones + pipeline de construcción VERITAS de 10 puertas. Juntos forman el stack de inteligencia soberana.

Licencia

MIT

Ollama-Omega