Гайды

Как настроить MCP в Ollama

18 октября 2026 · 15 минут чтения

Проверка фактов

Юлия Найпак

Методист по автоматизации. Сверяет паспорт инструмента с документацией вендора.

Автор Р

Редакция

Коллектив авторов, редакторов и иллюстраторов статей на сайте блога онлайн-университета «Зерокодер». Пишем…

Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.

Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 18 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.

Как настроить MCP в Ollama: собрать конфигурационный файл с описанием MCP-серверов и запустить поверх Ollama один из двух инструментов — мост ollama-mcp-bridge или терминальный клиент ollmcp. Мост ставит API-слой перед Ollama и подключает инструменты нескольких MCP-серверов так, что каждый запрос к Ollama видит все подключённые инструменты. Клиент ollmcp даёт интерактивный терминал, где инструменты, модели и серверы управляются в реальном времени. Оба пути описаны в документации проектов на GitHub. Мы скачали подборку результатов веб-поиска по запросу «Как настроить MCP в Ollama»: текст отдали 10 из 10.

Прямой ответ и границы продукта

Ollama — это локальный сервер моделей. MCP (Model Context Protocol) — протокол, по которому модель получает доступ к инструментам: файлам, базам, поиску, браузеру. Сам по себе Ollama инструменты MCP не исполняет. Между ними ставится посредник, и в прочитанном корпусе таких посредников два.

Первый — ollama-mcp-bridge. В документации проекта сказано: он «Provides an API layer in front of the Ollama API, seamlessly adding tools from multiple MCP servers so every Ollama request can access all connected tools transparently». То есть мост поднимает собственный HTTP-сервер, принимает запросы в формате Ollama и добавляет к ним инструменты.

Второй — ollmcp, «MCP Client for Ollama». В README проекта он описан как «a modern, interactive terminal application (TUI) built for harness engineering, connecting local Ollama LLMs to one or more Model Context Protocol (MCP) servers». Это терминальное приложение: вы запускаете его, оно соединяется с Ollama и с MCP-серверами, и дальше вы работаете в диалоге.

Границы, которые важно держать в голове:

• Мост интегрирует инструменты MCP только в один эндпоинт — POST /api/chat. Документация формулирует это прямо: «This is the only endpoint where MCP server tools are integrated». Остальные эндпоинты (кроме /api/chat, /health и /version) проксируются в Ollama без изменений, и существующие клиенты Ollama продолжают работать как обычно.
• Клиент ollmcp — отдельное приложение со своим интерфейсом; он не превращает ваш обычный HTTP-клиент в MCP-клиент.
• Оба инструмента работают с локальными моделями Ollama. Мост дополнительно принимает адрес удалённого или облачного сервера Ollama через параметр --ollama-url.

Выбор простой. Нужно, чтобы ваше приложение или скрипт ходило в Ollama по HTTP и при этом могло вызывать инструменты, — берите мост. Нужно вручную пробовать инструменты, переключать модели и смотреть, что происходит, — берите ollmcp.

Условия доступа и источник актуальных требований

Актуальные требования живут в README проектов на GitHub: jonigl/ollama-mcp-bridge для моста и jonigl/mcp-client-for-ollama для клиента. Там же лежат разделы «Requirements», «Quick Start» и «Configuration». Это первоисточник, и сверяться нужно с ним: версии зависимостей и набор флагов меняются от релиза к релизу.

Что требуется по документации:

• Работающий сервер Ollama. Мост обращается к нему по адресу, который задаётся переменной OLLAMA_URL (по умолчанию http://localhost:11434) либо флагом --ollama-url. Документация отмечает, что это удобно для Docker-развёртываний и управления конфигурацией.
• Конфигурационный файл минимум с одним MCP-сервером. В требованиях моста сказано: «MCP server configuration file with at least one MCP server defined». По умолчанию берётся ./mcp-config.json.
• Среда выполнения для серверов. Для Node.js-серверов используется npx, для Python — uv. В README моста перечислены допустимые команды, и npx указан как рабочий вариант для серверов на Node.js.
• Python-окружение для установки. Клиент ollmcp ставится через uv tool install --upgrade ollmcp или pip install --upgrade ollmcp.

Отдельно про Docker. Документация моста предупреждает: «When running in Docker, MCP servers should use commands available in the container». Конфигурация монтируется внутрь томами, а рабочая директория выставляется в /, чтобы относительные пути в mcp-config.json разрешались правильно.

Сетевые обращения зависят от выбранной схемы: посредник обращается к локальному или удалённому серверу модели и к MCP-серверам. Ollmcp также поддерживает облачные и OpenAI-совместимые провайдеры. Условия доступа следует проверять для каждого подключённого сервиса.

Порядок действий: мост ollama-mcp-bridge

Разберём путь от пустой папки до работающего вызова инструмента.

Шаг 1. Установить мост. Для варианта PyPI README приводит pip install --upgrade ollama-mcp-bridge. Также описаны Docker Compose, Docker и установка из исходников; далее используем установленную CLI-команду.

Шаг 2. Создать mcp-config.json. Документация говорит: «Create an MCP configuration file at mcp-config.json with your servers». Структура — объект mcpServers, где ключ — имя сервера, а значение — описание запуска. Пример из документации включает сервер погоды на uv, удалённый сервер по StreamableHTTP, удалённый сервер по SSE и файловый сервер на npx с фильтром инструментов.

Шаг 3. Настроить фильтрацию инструментов. Параметр toolFilter управляет тем, какие инструменты сервера увидят модели. Документация: «You can filter which tools from an MCP server are made available to Ollama using the optional toolFilter configuration». Режим include перечисляет разрешённые инструменты, режим exclude — запрещённые. В примере для файлового сервера исключены delete_file и write_file.

Шаг 4. Запустить мост. Базовая команда — ollama-mcp-bridge, она берёт ./mcp-config.json, слушает 0.0.0.0 на порту 8000. Дальше параметры настраиваются флагами:

• --config /path/to/custom-config.json — другой файл конфигурации;
• --host и --port — адрес и порт прослушивания;
• --ollama-url http://192.168.1.100:11434 — адрес сервера Ollama;
• --max-tool-rounds 5 — ограничение числа раундов вызова инструментов;
• --system-prompt "..." — системная подсказка, добавляемая ко всем запросам на /api/chat;
• --upstream-header "X-API-Key: your-key" — дополнительный заголовок к вышестоящему серверу, флаг можно повторять.

Шаг 5. Отправить запрос на /api/chat. Документация описывает цикл так: запрос уходит в Ollama вместе со списком доступных инструментов; если Ollama решает вызвать инструмент, вызов исполняется через соответствующий MCP-сервер; ответ инструмента возвращается в Ollama; цикл повторяется, пока вызовы нужны; ответы стримятся клиенту по ходу процесса. Итоговый ответ приходит со встроенными результатами инструментов.

Шаг 6. Проверить здоровье. У моста есть эндпоинты /health и /version. Если заданы заголовки --upstream-header, они добавляются и к проверкам здоровья, и ко всем запросам к вышестоящему серверу.

Отдельная деталь про переменные. В конфигурации поддерживается подстановка: ${workspaceFolder} разворачивается в путь рабочей папки, ${env:MCP_REQUEST_TAG} берёт значение из переменной окружения. Это позволяет держать секреты вне файла конфигурации.

Порядок действий: клиент ollmcp

Второй путь — терминальный клиент. Он удобен тем, что серверы добавляются одной командой, а результат виден сразу.

Установка. Документация даёт две команды: uv tool install --upgrade ollmcp или pip install --upgrade ollmcp.

Добавление сервера. Команда ollmcp mcp add работает по образцу claude mcp. Синтаксис из документации:

• удалённые серверы: ollmcp mcp add --transport http <name> <url> и ollmcp mcp add --transport sse <name> <url>;
• локальные stdio-серверы: ollmcp mcp add [options] <name> -- <command> [args...], где всё после -- — команда запуска;
• список серверов: ollmcp mcp list;
• удаление: ollmcp mcp remove <name>.

Транспорт stdio используется по умолчанию. Примеры из документации: ollmcp mcp add --transport stdio playwright npx @playwright/mcp@latest и ollmcp mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /allowed-dir1 ~/allowed-dir2.

Области видимости. У серверов три области, и они описаны в документации таблицей:

Область project пишет стандартный .mcp.json в корень проекта, совместимый с Claude Code и другими MCP-инструментами. Если одно имя сервера встречается в нескольких областях, приоритет такой: local > project > user.

Запуск. Команда ollmcp без флагов подключается ко всем серверам, добавленным через ollmcp mcp add, и берёт модель из сохранённой конфигурации либо первую доступную модель Ollama. Внутри работает /help со списком интерактивных команд.

Флаги. Документация перечисляет: --servers-json (или -j) — путь к JSON-файлу с конфигурацией серверов; --mcp-server (или -s) — путь к одному или нескольким скриптам MCP-серверов, флаг можно повторять; --mcp-server-url (или -u) — URL одного или нескольких SSE- или Streamable HTTP-серверов; --claude-desktop — загрузка серверов из конфигурации Claude Desktop; --host (или -H) — адрес Ollama.

Приоритет слоёв. Серверы, добавленные через ollmcp mcp add, всегда загружаются базовым слоем. Флаги --mcp-server, --mcp-server-url, --servers-json, --claude-desktop добавляются поверх. Документация предупреждает: если сервер с тем же именем приходит и через реестр, и через флаг, открываются оба соединения, но активным остаётся одно. Имена серверов из реестра в флагах лучше не повторять.

Горячая перезагрузка. Команда /reload-servers (сокращённо /rs) перезагружает все MCP-серверы с текущей конфигурацией. Это заметно ускоряет отладку собственного сервера: правите код, перезагружаете, проверяете.

Учебный пример и критерии проверки

Соберём минимальный сценарий, который проверяет всю цепочку. Это наше упражнение.

Задача. Подключить файловый MCP-сервер и убедиться, что модель действительно вызывает его инструмент.

Конфигурация. Создайте mcp-config.json; ниже оставлен файловый сервер из примера README:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "toolFilter": {
        "mode": "exclude",
        "tools": ["delete_file", "write_file"]
      }
    }
  }
}

Замените /tmp своим существующим учебным каталогом. Фильтр исключает перечисленные имена; полный набор инструментов проверяйте по описанию файлового сервера.

Запуск. При работающем Ollama запустите ollama-mcp-bridge --config mcp-config.json --ollama-url http://localhost:11434. Для учебного запроса используйте свой Ollama-клиент с адресом моста http://localhost:8000 и эндпоинтом /api/chat. Выберите модель с поддержкой вызова инструментов и попросите перечислить файлы учебного каталога.

Что считать успехом. Сопоставьте показанные имена с реальными файлами и проверьте в журнале фактический вызов MCP-инструмента и его результат. Текстовый ответ без вызова инструмента не подтверждает прохождение всей цепочки. Если модель отказалась, отдельно проверьте подключение сервера, доступные инструменты и поддержку tool calling у модели.

Критерии самостоятельной проверки. Четыре точки, по которым видно, где порвалась цепочка:

1. Мост поднялся. Запрос на /health отвечает. Если нет — проблема в запуске или порте.
2. Серверы подключились. В логах моста видно, что серверы из конфигурации загружены и соединены. Документация описывает это так: «All MCP servers defined in the configuration are loaded and connected».
3. Инструменты дошли до модели. Если фильтр include перечисляет инструменты, а модель их не видит, проверьте имена: они должны совпадать с теми, что объявляет сервер.
4. Модель умеет вызывать инструменты. Не всякая локальная модель это делает. Возьмите модель, которая уверенно работает с вызовом функций, и повторите запрос.

Для клиента ollmcp проверка проще: запустите ollmcp, наберите /help, посмотрите список серверов и инструментов. Команда /reload-servers перечитает конфигурацию после правок.

Тот же приём работает и для других моделей: если вы уже запускали локальные модели, посмотрите сравнение Gemma и Qwen — там разбирается, чем модели отличаются по поведению в задачах с инструментами.

Смежные варианты и выбор по задаче

Оба инструмента решают одну задачу разными способами. Разберём, что выбирать в конкретных ситуациях.

Скрипт или приложение ходит в Ollama по HTTP. Мост. Он встаёт перед Ollama и не требует менять код клиента: запросы на /api/chat получают поддержку инструментов, остальные эндпоинты проксируются без изменений. Документация подчёркивает, что существующие клиенты и библиотеки Ollama продолжают работать как обычно.

Нужно вручную исследовать инструменты. Клиент ollmcp. Он даёт терминал с автодополнением, переключением моделей, управлением инструментами и режимом Human-in-the-Loop, когда вы подтверждаете каждый вызов.

Нужно несколько серверов сразу. Оба варианта поддерживают множественные подключения. Мост подключает все серверы из конфигурации на старте. Клиент открывает соединения со всеми серверами, добавленными в реестр.

Нужна тонкая настройка доступа. Мост: toolFilter с режимами include и exclude плюс подстановка переменных ${workspaceFolder} и ${env:...}. Клиент: области видимости local, project, user и флаг --claude-desktop для переноса серверов из Claude Desktop.

Нужна безопасность вызовов. Клиент ollmcp: режим Human-in-the-Loop, при котором вы подтверждаете выполнение инструмента. Документация относит его к строгим мерам контроля.

Нужна отладка собственного сервера. Клиент: /reload-servers перезагружает серверы без перезапуска приложения. Мост в такой ситуации требует перезапуска.

Нужен удалённый сервер. Оба поддерживают SSE и Streamable HTTP. Мост принимает URL прямо в конфигурации; клиент — через --transport http или --transport sse при добавлении.

Отдельно стоит сказать про модели. Вызов инструментов — навык, который зависит от модели. Если вы только выбираете, с чего начать локально, пригодится материал о том, как скачать Command R и запустить его локально: там описан порядок работы с весами и локальным запуском.

Типичные проблемы и способы диагностики

Ошибки при настройке MCP почти всегда упираются в одно из пяти мест. Разберём каждое с проверкой.

Модель отвечает, но инструмент не вызывает. Первое, что нужно исключить, — сама модель. Возьмите заведомо инструментальную модель и повторите запрос. Второе — фильтр инструментов: если в toolFilter стоит include с именами, которых сервер не объявляет, модель этих инструментов не увидит. Третье — эндпоинт: у моста инструменты работают только на /api/chat. Запрос на другой эндпоинт уйдёт в Ollama без инструментов, и это ожидаемое поведение.

Локальный сервер не стартует. Проверьте команду запуска. Для Node.js-серверов документация называет рабочей командой npx. Если сервер запускается в Docker, команда должна существовать внутри контейнера. Отдельная тонкость из документации моста: директорию с mock-сервером монтируют без флага :ro, чтобы uv мог создать внутри .venv.

Удалённый сервер не подключается. Проверьте транспорт. Для Streamable HTTP и SSE в конфигурации указывается url; для SSE в клиенте ollmcp — type: "sse", для HTTP — type: "streamable_http". Если сервер требует авторизации, заголовки задаются в конфигурации: в примерах документации клиента это headers с Authorization и X-API-Key.

Инструменты пропали после правки конфигурации. В клиенте ollmcp выполните /reload-servers. В мосте перезапустите процесс: серверы подключаются на старте из JSON-конфигурации.

Ответ обрывается. У клиента ollmcp логи пишутся в ~/.config/ollmcp/logs/<session>/. Документация описывает две категории файлов: <server>.log для каждого сервера и ollmcp.log для самого клиента. Второй пишется на каждом запуске без флага --debug, и именно на него указывает предупреждение на экране, когда поток ответа заканчивается рано. Сейчас туда попадают в основном ошибки провайдера и стриминга.

Ключ не подхватывается. В клиенте ollmcp порядок разрешения ключей такой: сохранённый в ~/.config/ollmcp/config.json ключ провайдера имеет приоритет над переменной окружения провайдера. Документация предупреждает: если вы однажды сохранили неверный или просроченный ключ, установка переменной окружения его не перекроет. Лечится либо передачей правильного ключа через --api-key, либо удалением устаревшего apiKey из профиля провайдера в файле конфигурации.

Конфигурация не читается. Проверьте JSON на синтаксис. Структура верхнего уровня — объект mcpServers, внутри — именованные серверы. Для stdio-сервера указываются command, args, при необходимости env; для удалённых — url и headers. Поле disabled позволяет временно отключить сервер, не удаляя его описание.

Серверы дублируются. Если одно имя приходит и из реестра ollmcp mcp add, и через флаг, документация отмечает: открываются оба соединения, активным остаётся одно. Проверьте ollmcp mcp list и уберите лишнее.

Частые вопросы

Как подключить MCP к Ollama?

Нужен посредник между Ollama и MCP-серверами. Документация проекта ollama-mcp-bridge описывает мост, который встаёт перед API Ollama и добавляет инструменты всех подключённых серверов. Второй вариант — терминальный клиент ollmcp: он соединяет локальные модели Ollama с одним или несколькими MCP-серверами. В обоих случаях вы создаёте описание серверов в JSON и запускаете инструмент.

Что такое ollama mcp server?

Это MCP-сервер, который вы подключаете к Ollama через посредника. В документации моста конфигурация задаётся объектом mcpServers, где каждый сервер описан командой запуска или URL. Серверы бывают локальными (запускаются как процесс через npx или uv) и удалёнными (доступны по HTTP или SSE). Набор инструментов сервера можно ограничить через toolFilter.

Почему модель не вызывает инструменты?

Причин обычно три. Модель может не уметь вызывать функции — проверьте на инструментальной модели. Фильтр toolFilter в режиме include может не содержать нужных имён. Запрос может уходить не на тот эндпоинт: у моста инструменты подключены только к POST /api/chat, остальные эндпоинты проксируются в Ollama без изменений.

Где хранится конфигурация MCP-серверов?

У моста — файл mcp-config.json в текущей директории по умолчанию, путь меняется флагом --config. У клиента ollmcp — три области: local пишет ~/.config/ollmcp/mcp.local.json, project пишет .mcp.json в корне проекта, user пишет ~/.config/ollmcp/mcp.json. При совпадении имён приоритет такой: local, затем project, затем user.

Как обновить конфигурацию без перезапуска?

В клиенте ollmcp есть команда /reload-servers с сокращением /rs: она перезагружает все MCP-серверы с текущей конфигурацией. Документация относит горячую перезагрузку к средствам быстрой разработки. У моста серверы подключаются на старте из JSON-конфигурации, поэтому после правки файла процесс перезапускают.