Ollama-Omega MCP server

Усиленный MCP-сервер, который связывает полную экосистему Ollama — как локальные модели, так и облачные гиганты — с любой IDE, поддерживающей MCP. Никаких скриптов-оберток. Никаких раздутых SDK. Только один файл Python с двумя зависимостями.

ПРИНЦИП ПРОЕКТИРОВАНИЯ: Ollama-Omega не абстрагирует Ollama. Он предоставляет полный API Ollama через 6 проверенных инструментов с обработкой ошибок без потери информации.

Архитектура

┌─────────────────────────────────────────────────────┐
│                    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)      │
└───────────────────────────────────────────────────────┘

Инструменты (6)

Инструмент	Назначение
`ollama_health`	Проверка соединения и список запущенных/загруженных моделей
`ollama_list_models`	Список всех доступных моделей с размером, статусом загрузки и датой изменения
`ollama_chat`	Отправка запроса на завершение чата с историей сообщений и системным промптом
`ollama_generate`	Генерация ответа на заданный промпт без истории чата
`ollama_show_model`	Отображение подробной информации о конкретной модели (лицензия, параметры)
`ollama_pull_model`	Загрузка модели из библиотеки Ollama

Аудит безопасности

#	Категория	Мера защиты
1	SSRF	Перенаправления отключены в клиенте httpx (`follow_redirects=False`)
2	Утечка ресурсов	Синглтон `AsyncClient` — один пул соединений на время жизни сервера
3	Валидация ввода	Проверка `_validate_required()` для каждого инструмента перед любым HTTP-вызовом
4	Безопасность JSON	Обертка `_safe_json()` — никогда не падает при некорректных ответах
5	Структурированное логирование	Весь вывод stderr через модуль `logging`, а не через обычный `print()`
6	DRY-полезные нагрузки	`_build_options()` централизует маппинг температуры/токенов
7	Санитизация ошибок	Хелпер `_error()` — никаких трассировок стека, внутренние данные не утекают клиенту

Быстрый старт

Требования

Python 3.11+
pip install mcp httpx

Настройка в 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"
      }
    }
  }
}

Переменные окружения

Переменная	По умолчанию	Описание
`OLLAMA_HOST`	`http://localhost:11434`	URL демона Ollama
`OLLAMA_TIMEOUT`	`300`	Тайм-аут запроса в секундах (длительный для загрузки больших моделей/облачного вывода)
`PYTHONUTF8`	—	Установите в `1` для безопасности Unicode в Windows

Облачные модели

Ollama-Omega не зависит от версии. Если ваш демон Ollama предоставляет доступ к облачным моделям (например, qwen3.5:397b-cloud через API-прокси), они доступны через те же 6 инструментов — изменение конфигурации не требуется.

Структура файлов

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

Тестирование

pip install pytest
python -m pytest tests/ -v

48 тестов, охватывающих:

Определения инструментов — валидация схемы, обязательные поля, описания
Вспомогательные функции — построитель опций, валидация, безопасность JSON, форматирование ошибок
Диспетчер — все 6 путей инструментов с мокированными HTTP-ответами
Обработка ошибок — соединение, тайм-аут, HTTP-статус, санитизация исключений
Конфигурация — значения по умолчанию, защита от SSRF, идентификация сервера

Сопутствующий сервер

Ollama-Omega является транспортным уровнем для Omega Brain MCP — эпизодическая память между сессиями + 10-шлюзовый конвейер сборки VERITAS. Вместе они образуют суверенный стек интеллекта.

Лицензия

MIT

Ollama-Omega