OpenSearch MCP: как подключить кластер к Claude, Cursor и Codex

opensearch-project/opensearch-mcp-server-py· Проверено 12.11.2026· 158на GitHub

Подключает агента к кластеру OpenSearch: искать по индексам на Query DSL и PPL, читать маппинги, шарды и здоровье кластера, вызывать любой эндпоинт API.

По умолчанию включены 9 основных инструментов; наблюдаемость, анализ логов, Search Relevance Workbench и память агента включаются категориями.

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

Что сделать до подключения

uv с командой uvx или pip install opensearch-mcp-server-py

Доступ к кластеру OpenSearch: адрес и логин с паролем, роль IAM или ключи AWS

OPENSEARCH_URL

Адрес кластера со схемой http:// или https://; для локального OpenSearch пишите порт явно: http://localhost:9200

OPENSEARCH_USERNAME / OPENSEARCH_PASSWORD

Логин и пароль базовой авторизации; для кластера без авторизации вместо них OPENSEARCH_NO_AUTH=true

Конфиг для вашего клиента

Команда в терминале, в папке проекта. Флаг --scope user подключит сервер для всех проектов. Подробно о Claude Code

claude mcp add --env 'OPENSEARCH_URL=<адрес кластера, например http://localhost:9200>' --env 'OPENSEARCH_USERNAME=<логин>' --env 'OPENSEARCH_PASSWORD=<пароль>' --transport stdio opensearch \
  -- uvx opensearch-mcp-server-py

Проверка: claude mcp list показывает статус рядом с каждым сервером: ✔ Connected, ! Needs authentication или ✘ Failed to connect. Внутри сессии то же видно по команде /mcp.

Файл ~/.codex/config.toml или .codex/config.toml в доверенном проекте. Можно и командой codex mcp add. Подробно о Codex

[mcp_servers.opensearch]
command = "uvx"
args = ["opensearch-mcp-server-py"]

[mcp_servers.opensearch.env]
OPENSEARCH_URL = "<адрес кластера, например http://localhost:9200>"
OPENSEARCH_USERNAME = "<логин>"
OPENSEARCH_PASSWORD = "<пароль>"

Проверка: В интерфейсе codex введите /mcp: появится список активных серверов. Из терминала то же покажет codex mcp list.

Файл ~/.cursor/mcp.json для всех проектов или .cursor/mcp.json в папке проекта. Подробно о Cursor

{
  "mcpServers": {
    "opensearch": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py"],
      "env": {
        "OPENSEARCH_URL": "<адрес кластера, например http://localhost:9200>",
        "OPENSEARCH_USERNAME": "<логин>",
        "OPENSEARCH_PASSWORD": "<пароль>"
      }
    }
  }
}

Проверка: Откройте Customize в боковой панели: там список серверов с переключателями. Ошибки подключения смотрите в панели Output (Cmd+Shift+U), пункт MCP Logs в выпадающем списке.

Файл .mcp.json в корне проекта или ~/.copilot/mcp-config.json для всех проектов. Подробно о VS Code

{
  "mcpServers": {
    "opensearch": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opensearch-mcp-server-py"],
      "env": {
        "OPENSEARCH_URL": "<адрес кластера, например http://localhost:9200>",
        "OPENSEARCH_USERNAME": "<логин>",
        "OPENSEARCH_PASSWORD": "<пароль>"
      }
    }
  }
}

Проверка: Попросите Copilot выполнить безобидную задачу через сервер и раскройте вызов инструмента в чате. Одна запись в конфиге подключение не подтверждает.

Файл ~/.qwen/settings.json или .qwen/settings.json в проекте. Подробно о Qwen Code

{
  "mcpServers": {
    "opensearch": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py"],
      "env": {
        "OPENSEARCH_URL": "<адрес кластера, например http://localhost:9200>",
        "OPENSEARCH_USERNAME": "<логин>",
        "OPENSEARCH_PASSWORD": "<пароль>"
      }
    }
  }
}

Проверка: Запустите qwen и введите /mcp: откроется окно управления серверами. Из терминала статус покажет qwen mcp list.

Файл ~/.gemini/settings.json или .gemini/settings.json в проекте. Подробно о Gemini CLI

{
  "mcpServers": {
    "opensearch": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py"],
      "env": {
        "OPENSEARCH_URL": "<адрес кластера, например http://localhost:9200>",
        "OPENSEARCH_USERNAME": "<логин>",
        "OPENSEARCH_PASSWORD": "<пароль>"
      }
    }
  }
}

Проверка: gemini mcp list показывает каждый сервер, его настройки и статус Connected или Disconnected. В сессии /mcp выводит CONNECTED, CONNECTING или DISCONNECTED и список инструментов.

Файл opencode.json в папке проекта или ~/.config/opencode/opencode.json. Подробно о OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "opensearch": {
        "type": "local",
        "command": ["uvx", "opensearch-mcp-server-py"],
        "environment": {
          "OPENSEARCH_URL": "<адрес кластера, например http://localhost:9200>",
          "OPENSEARCH_USERNAME": "<логин>",
          "OPENSEARCH_PASSWORD": "<пароль>"
        }
      }
    }
  }
}

Проверка: opencode mcp list показывает состояние каждого сервера, подключённый выглядит как ✓ context7 connected. Внутри OpenCode то же видно в /mcps.

Настройки → Разработчик → Изменить конфиг: файл claude_desktop_config.json. После правки перезапустите приложение. Подробно о Claude Desktop

{
  "mcpServers": {
    "opensearch": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py"],
      "env": {
        "OPENSEARCH_URL": "<адрес кластера, например http://localhost:9200>",
        "OPENSEARCH_USERNAME": "<логин>",
        "OPENSEARCH_PASSWORD": "<пароль>"
      }
    }
  }
}

Проверка: Нажмите «Add files, connectors, and more /» в левом нижнем углу поля ввода, наведите на Connectors и откройте Manage connectors. Выберите сервер, чтобы увидеть его инструменты.

Вкладка Program → Install → Edit mcp.json. Подробно о LM Studio

{
  "mcpServers": {
    "opensearch": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py"],
      "env": {
        "OPENSEARCH_URL": "<адрес кластера, например http://localhost:9200>",
        "OPENSEARCH_USERNAME": "<логин>",
        "OPENSEARCH_PASSWORD": "<пароль>"
      }
    }
  }
}

Проверка: Попросите модель в чате выполнить задачу через инструмент сервера. Через API сервер из mcp.json вызывают по id в integrations, например mcp/playwright.

Инструменты сервера

ListIndexToolвыводит индексы и их размеры

IndexMappingToolчитает маппинг и настройки индекса

SearchIndexToolищет по индексу на Query DSL

CountToolсчитает документы по запросу

ExplainToolобъясняет, почему документ подошёл

MsearchToolвыполняет несколько поисков разом

GetShardsToolпоказывает шарды

ClusterHealthToolпоказывает здоровье кластера

GenericOpenSearchApiToolвызывает любой эндпоинт API

GetClusterStateToolчитает состояние кластера

CatNodesToolпоказывает нагрузку на узлы

GetIndexStatsToolчитает статистику индекса

GetQueryInsightsToolпоказывает топ тяжёлых запросов

GetNodesHotThreadsToolпоказывает горячие потоки узлов

GetLongRunningTasksToolпоказывает долгие задачи

PPLQueryToolвыполняет запрос на PPL

LogPatternAnalysisToolищет аномальные шаблоны в логах

MetricChangeAnalysisToolнаходит метрики, которые сдвинулись

CreateExperimentToolзапускает эксперимент релевантности

SaveMemoryToolсохраняет память агента

Показано 20 из 52.

Что попросить агента

«Покажи все индексы кластера и их размер»Агент вызовет ListIndexTool

«Почему документ <ID> не находится по запросу <запрос> в индексе <индекс>?»Агент посмотрит маппинг через IndexMappingTool и разберёт совпадение через ExplainTool

«Кластер тормозит: найди, что его грузит»Агент проверит ClusterHealthTool, CatNodesTool, GetNodesHotThreadsTool и GetLongRunningTasksTool

«Сравни логи <индекс> за последний час с прошлыми сутками и найди, что изменилось»Агент вызовет LogPatternAnalysisTool и MetricChangeAnalysisTool (категория skills)

Для каких задач

Найти документы по запросу и объяснить, почему документ попал или не попал в выдачу

Проверить здоровье кластера, шарды, узлы и долгие задачи

Найти самые тяжёлые запросы и горячие потоки на узлах

Сравнить логи за два периода и найти аномальные шаблоны и сдвинувшиеся метрики

Собрать эксперимент релевантности поиска с оценками от LLM

Работать с несколькими кластерами в одной сессии

Ограничения

Запись по умолчанию разрешена (OPENSEARCH_SETTINGS_ALLOW_WRITE=true): для работы только на чтение поставьте false

Если в OPENSEARCH_URL нет порта, сервер подставляет 443 или 80: для локального OpenSearch указывайте :9200 явно

Ответ больше 10 МБ сервер обрывает с ошибкой ResponseSizeExceededError; лимит меняется в OPENSEARCH_MAX_RESPONSE_SIZE

Память агента на SaveMemoryTool требует Amazon OpenSearch Service 2.19+ или Serverless, Agentic Memory — OpenSearch 3.3.0 или новее

Если не работает

Response size exceeded limit of 10485760 bytes

Ответ кластера больше лимита: сузьте запрос, добавьте пагинацию или поднимите OPENSEARCH_MAX_RESPONSE_SIZE.

Инструмент падает с ошибкой на старой версии OpenSearch

Инструмент несовместим с версией кластера: ошибка приходит при вызове. Agentic Memory, например, требует OpenSearch 3.3.0 или новее.

Вызов с opensearch_url падает и просит данные входа

Сервер не подставляет свои учётные данные к чужому адресу: передайте в том же вызове логин и пароль, ключи AWS с регионом или opensearch_no_auth.

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

Можно запустить без адреса кластера в конфиге?

Да: при запуске uvx opensearch-mcp-server-py без переменных агент передаёт opensearch_url и данные входа в каждом вызове инструмента. Так одна сессия работает с несколькими кластерами.

Как включить инструменты, которых нет по умолчанию?

Задайте категории в OPENSEARCH_ENABLED_CATEGORIES: observability для PPL, skills для анализа логов и метрик, analytics для обеих, search_relevance для Search Relevance Workbench, agentic_memory для памяти OpenSearch. Отдельные инструменты включаются через OPENSEARCH_ENABLED_TOOLS.

Как запретить агенту изменять данные?

Поставьте OPENSEARCH_SETTINGS_ALLOW_WRITE=false. Чтобы разрешить запись только части инструментов, перечислите их категории в OPENSEARCH_SETTINGS_ALLOW_WRITE_CATEGORIES.

Какие способы входа поддерживаются?

Без авторизации, токен Bearer из заголовка, логин и пароль, роль IAM, ключи или профиль AWS, mTLS. Для OpenSearch Serverless задайте AWS_OPENSEARCH_SERVERLESS=true.

Работает ли сервер из России?

Сервер запускается на вашем компьютере и ходит в ваш кластер OpenSearch, в том числе развёрнутый у себя: аккаунт AWS нужен только для Amazon OpenSearch Service.