Couchbase

Couchbase MCP Server

Couchbase MCP Server — это самостоятельно размещаемый сервер Model Context Protocol (MCP), который подключает AI-агентов и ассистентов на базе LLM — Claude, Cursor, Windsurf, VS Code Copilot и другие MCP-клиенты — к данным в кластерах Couchbase, размещенных на Capella или управляемых самостоятельно. MCP — это открытый стандарт, позволяющий AI-ассистентам вызывать инструменты и запрашивать внешние источники данных; этот сервер реализует данный стандарт для Couchbase, поэтому AI-агент может проверять ваш кластер, выполнять SQL++-запросы, читать и записывать документы, а также анализировать производительность запросов на естественном языке вместо рукописного кода.

Он предоставляет инструменты по категориям, включая здоровье кластера, схему данных, Key-Value, запросы и производительность — с мерами безопасности через режим только для чтения (включен по умолчанию) и детальным отключением инструментов, что позволяет AI-агенту исследовать и запрашивать данные без риска непреднамеренных записей. Поддерживаются транспорты STDIO и Streamable HTTP.

Couchbase MCP Server распространяется как пакет Python Package Index (PyPI) и через Docker. Корпоративная поддержка Couchbase MCP Server доступна при лицензировании Couchbase AI Data Plane, что также дает право на использование и корпоративную поддержку Couchbase Agent Memory и Couchbase Agent Catalog.

Полную документацию см. на mcp-server.couchbase.com.

Полную документацию см. на docs.couchbase.com/mcp-server.

Содержание

• Зачем нужен Couchbase MCP Server
• Примеры запросов
• Возможности/Инструменты
• Предварительные требования
• Конфигурация
• Сервер Operational Insights
• Режим транспорта Streamable HTTP
• Режим транспорта SSE
• Авторизация OAuth 2.1
• Docker-образ
• Сбор данных об использовании
• Советы по устранению неполадок
• Интеграционное тестирование
• FAQ
• Участие в разработке
• Политика поддержки

Зачем нужен Couchbase MCP Server

• Безопасен по умолчанию — операции записи (upsert/insert/delete документов и изменяющие данные SQL++-запросы) блокируются, если вы явно не установите CB_MCP_READ_ONLY_MODE=false, а отдельные инструменты можно отключить или ограничить подтверждением пользователя.
• Работает с Capella и самостоятельно управляемыми кластерами — одна и та же конфигурация подключается к Couchbase Capella (полностью управляемый) или к самостоятельно размещенному кластеру Couchbase Server.
• С учетом RBAC — отключение инструментов — это удобный слой для направления поведения LLM; лежащий в основе контроль доступа на основе ролей пользователя Couchbase остается авторитетной границей безопасности.
• Продакшн-транспорты — работа через STDIO для локальных настольных клиентов или Streamable HTTP с опциональной авторизацией OAuth 2.1 (JWT/JWKS, независимо от провайдера — Auth0, Okta, Keycloak, Entra, Cognito и т. д.) для общих/удаленных развертываний.
• Любой MCP-клиент — протестировано с Claude Desktop, Cursor, Windsurf, VS Code и JetBrains AI Assistant/Junie; работает с любым клиентом, реализующим спецификацию MCP.

Примеры запросов

После подключения сервера вы можете общаться с кластером Couchbase на естественном языке через AI-ассистента. Например:

• "Какие buckets, scopes и collections есть в этом кластере, и какова схема коллекции orders?"
• "Выполни SQL++-запрос, чтобы найти 10 самых последних документов в коллекции users where status = 'active'."
• "Какие 5 самых медленных запросов в этом кластере за последний час, и отсутствует ли у каких-либо из них покрывающий индекс?"
• "Проверь, здоров ли этот кластер, и скажи, какие службы работают."
• "Вставь новый документ в коллекцию products с такими полями: ..." (требуется CB_MCP_READ_ONLY_MODE=false)

Возможности/Инструменты

Этот дистрибутив включает два сервера: операционный сервер (по умолчанию — таблицы непосредственно ниже) взаимодействует с обычным кластером Couchbase через SDK couchbase, а сервер Operational Insights (его собственная таблица ниже) взаимодействует с кластерами Operational Insights через SDK couchbase-operational-insights.

Инструменты настройки и здоровья кластера

Инструменты модели данных и обнаружения схемы

Инструменты операций с документами KV

Инструменты запросов и индексации

Инструменты полнотекстового поиска (FTS)

Требуется Couchbase Server 7.6+ и служба Search. Векторный поиск не поддерживается этими инструментами (см. отдельные инструменты векторного поиска).

Инструменты анализа производительности запросов

Инструменты Operational Insights

Регистрируются отдельным сервером operational-insights (см. Сервер Operational Insights ниже), а не сервером по умолчанию operational.

Инструменты Server Async Request API образуют поток запуск → опрос → отброс или отмена для длительных запросов: run_query_async возвращает query_handle, get_async_query_results опрашивается до тех пор, пока не сообщит о готовности (и возвращает строки), затем либо discard_async_query_results освобождает результаты, либо, для запроса, который все еще выполняется, cancel_async_query останавливает его.

Примечание: get_collections_in_scope, get_schema_for_collection, create_index и list_indexes существуют, с разным поведением, на обоих серверах. (get_server_configuration_status также появляется на обоих, но это намеренно один общий инструмент — та же реализация, та же форма результата — поэтому он не требует разграничения.) Каждый сервер — отдельный процесс, так что это проблема только если один MCP-клиент регистрирует одновременно и operational, и operational-insights — в этом случае разграничьте их на уровне конфигурации клиента (например, задав двум записям сервера разные имена в собственной конфигурации клиента).

Предварительные требования

• Python 3.10 или выше.
• Работающий кластер Couchbase. Самый простой способ начать — использовать бесплатный уровень Capella, который является полностью управляемой версией сервера Couchbase. Вы можете следовать инструкциям, чтобы импортировать один из образцов наборов данных или импортировать свои собственные.
• Установленный uv для запуска сервера.
• Установленный MCP-клиент, такой как Claude Desktop, для подключения сервера к Claude. Инструкции приведены для Claude Desktop и Cursor. Можно использовать и другие MCP-клиенты.

Конфигурация

MCP-сервер можно запустить либо из предварительно собранного пакета PyPI, либо из исходного кода с помощью uv.

Запуск из PyPI

Мы публикуем предварительно собранный пакет PyPI для MCP-сервера.

Конфигурация сервера с использованием предварительно собранного пакета для MCP-клиентов

Базовая аутентификация

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

или

mTLS

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

Примечание: Если у вас уже используются другие MCP-серверы в клиенте, вы можете добавить его в существующий объект mcpServers.

Запуск из исходного кода

MCP-сервер можно запустить из исходного кода, используя этот репозиторий.

Клонируйте репозиторий на свой локальный компьютер

git clone https://github.com/couchbase/mcp-server-couchbase.git

Конфигурация сервера с использованием исходного кода для MCP-клиентов

Это общая конфигурация для MCP-клиентов, таких как Claude Desktop, Cursor, Windsurf Editor.

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

Примечание: path/to/cloned/repo/mcp-server-couchbase/ должен быть путем к клонированному репозиторию на вашем локальном компьютере. Не забудьте завершающий слэш в конце!

Примечание: Если у вас уже используются другие MCP-серверы в клиенте, вы можете добавить его в существующий объект mcpServers.

Дополнительная конфигурация для MCP-сервера

Сервер можно настроить с помощью переменных окружения или аргументов командной строки:

Конфигурация режима только для чтения

CB_MCP_READ_ONLY_MODE — это единственный переключатель, управляющий операциями записи:

• Когда true (по умолчанию): Все операции записи (KV, Query, управление областями видимости/коллекциями и управление индексами) отключены. Все инструменты записи (KV: upsert, insert, replace, delete, sub-document mutate; управление областями видимости/коллекциями: create_scope, create_collection, delete_scope, delete_collection; управление индексами: create_index, build_index, drop_index) не загружаются и не будут доступны LLM, а SQL++ запросы, изменяющие данные или структуру, блокируются.
• Когда false: Все инструменты записи загружаются, и SQL++ запросы на изменение данных/структуры разрешены.

Это рекомендуемый безопасный вариант по умолчанию для предотвращения случайных изменений данных LLM.

Примечание: Для аутентификации вам нужны либо имя пользователя и пароль, либо пути к клиентскому сертификату и ключу. При желании вы можете указать путь к корневому сертификату CA, который будет использоваться для проверки сертификатов сервера. Если указаны и путь к клиентскому сертификату с ключом, и имя пользователя с паролем, для аутентификации будут использоваться клиентские сертификаты.

Отключение инструментов

Вы можете отключить отдельные инструменты, чтобы предотвратить их загрузку и предоставление MCP-клиенту. Отключенные инструменты не будут отображаться при обнаружении инструментов и не могут быть вызваны LLM.

Поддерживаемые форматы

Список через запятую:

# Environment variable
CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"

# Command line
uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id

Путь к файлу (по одному имени инструмента в строке):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

# Command line
uvx couchbase-mcp-server --disabled-tools disabled_tools.txt

Формат файла (например, disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Строки, начинающиеся с #, считаются комментариями и игнорируются.

Примеры конфигурации MCP-клиента

Использование списка через запятую:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"
      }
    }
  }
}

Использование пути к файлу (рекомендуется для большого количества инструментов):

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"
      }
    }
  }
}

Важное примечание по безопасности

Предупреждение: Отключение инструментов само по себе не гарантирует, что определенные операции не могут быть выполнены. Права RBAC (управление доступом на основе ролей) пользователя базовой базы данных являются авторитетным контролем безопасности.

Например, даже если вы отключите upsert_document_by_id и delete_document_by_id, изменения данных все равно могут выполняться через инструмент run_sql_plus_plus_query с использованием операторов DML SQL++ (INSERT, UPDATE, DELETE, MERGE), если только:

• CB_MCP_READ_ONLY_MODE не установлен в true (по умолчанию), ИЛИ
• пользователь базы данных не имеет необходимых прав RBAC для изменения данных

Рекомендация: Всегда настраивайте соответствующие права RBAC для учетных данных пользователя Couchbase в качестве основной меры безопасности. Используйте отключение инструментов как дополнительный уровень для управления поведением LLM и уменьшения поверхности атаки, а не как единственный контроль безопасности.

Запрос/подтверждение для вызовов инструментов

Вы можете требовать явного подтверждения пользователя для конкретных инструментов перед выполнением (когда MCP-клиент поддерживает запрос).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools поддерживает следующие форматы:

• Список через запятую
• Путь к файлу (по одному имени инструмента в строке, комментарии # поддерживаются)

Пример:

# Environment variable
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

# Command line
uvx couchbase-mcp-server --confirmation-required-tools delete_document_by_id,replace_document_by_id

При вызове указанного инструмента:

• Если клиент поддерживает запрос, пользователю предлагается подтвердить.
• Если клиент не поддерживает запрос, инструмент выполняется без подтверждения для обратной совместимости.

Вы также можете проверить версию сервера с помощью:

uvx couchbase-mcp-server --version

Ведение журнала

MCP-сервер по умолчанию ведет журнал в stderr. Ведение журнала настраивается с помощью переменных CB_MCP_LOG_*, перечисленных в Дополнительной конфигурации:

• CB_MCP_LOG_LEVEL — объем журналирования: info (по умолчанию) регистрирует события жизненного цикла и вызовы инструментов, debug добавляет подробные внутренние детали, а off отключает все журналирование.
• CB_MCP_LOG_SINKS — куда направляются журналы: stderr (по умолчанию), циклические файлы по уровням (file) или оба варианта. С file записывается один файл на уровень (например, mcp_server.info.log и mcp_server.error.log) по пути, заданному CB_MCP_LOG_FILE.
• Размер ротации — CB_MCP_LOG_ROTATION_MAX_SIZE_MB — это глобальный размер (в МБ), при котором каждый файл уровня ротируется. Переопределите отдельные уровни с помощью CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG), также в МБ, которые наследуют глобальное значение, если не заданы. Размер 0 (глобальный или для уровня) недопустим и возвращается к значению по умолчанию (1 МБ) с предупреждением при запуске. CB_MCP_LOG_MAX_BYTES (байты) устарел, но по-прежнему поддерживается для обратной совместимости; он игнорируется, если также задан CB_MCP_LOG_ROTATION_MAX_SIZE_MB, и выводит предупреждение об устаревании при запуске.
• Хранение — CB_MCP_LOG_RETENTION_BACKUP_COUNT задает, сколько ротированных резервных копий сохраняется для каждого уровня (исключая активный файл); значение по умолчанию 1 сохраняет прежнее поведение. Переопределите отдельные уровни с помощью CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG), которые наследуют глобальное значение, если не заданы. Установите количество в 0, чтобы сохранять только активный файл для этого уровня — он по-прежнему ограничен размером ротации (сбрасывается при ротации, а не резервируется).
• Снимок конфигурации сервера — когда активен приемник file, одноразовая запись (ОС, Python, версии зависимостей, транспорт, разрешенная конфигурация журналирования и конфигурация сервера с удаленными секретами) записывается в формате JSON в отдельный файл mcp_server_config.log.json (производный от базового CB_MCP_LOG_FILE). Он перезаписывается при каждом запуске, поэтому поддержка всегда имеет текущую конфигурацию, и она никогда не выходит за пределы циклического журнала.

# Enable debug logging to both stderr and rotating per-level files
uvx couchbase-mcp-server --log-level=debug --log-sinks=stderr,file

# Keep 30 rotated ERROR backups but only the live DEBUG file
uvx couchbase-mcp-server --log-level=debug --log-sinks=file \
  --log-error-retention-backup-count=30 --log-debug-retention-backup-count=0

Для получения дополнительных сведений см. документацию.

Конфигурация для конкретных клиентов

Сервер операционной аналитики

Наряду с сервером operational по умолчанию (тем, который описан в каждом разделе выше), этот дистрибутив поставляет второй сервер для кластеров Operational Insights, использующий отдельный SDK couchbase-operational-insights. Это другой продукт, чем обычный кластер Couchbase, и он работает как независимый процесс на собственном порту.

Запустите его, передав operational-insights в качестве подкоманды CLI (или добавив его как команду контейнера):

uvx couchbase-mcp-server operational-insights
# or, from source:
uv run src/mcp_server.py operational-insights
# or, via Docker:
docker run --rm -i \
  -e CB_OI_CONNECTION_STRING=http://localhost:8095 \
  -e CB_OI_USERNAME=Administrator \
  -e CB_OI_PASSWORD=password \
  couchbase/mcp-server:<version> operational-insights

--connection-string — это URL HTTP(S), а не строка подключения couchbase:// — например, http://localhost:8095 для локального сервера Operational Insights или https://<host>:18095 для Capella. Это самая частая ошибка конфигурации при направлении этого сервера на кластер.

Все остальные флаги (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) идентичны флагам операционного сервера — см. Дополнительная конфигурация для MCP-сервера — за исключением значений по умолчанию для порта (8001, не 8000) и файла журнала (mcp_server_operational_insights.log, не mcp_server.log), поскольку два сервера не могут совместно использовать ни то, ни другое. OAuth использует те же метки областей (couchbase-mcp:read / couchbase-mcp:write), что и операционный сервер, поэтому существующая конфигурация IdP работает для обоих без изменений.

Пример конфигурации MCP-клиента:

{
  "mcpServers": {
    "couchbase-operational-insights": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OI_CONNECTION_STRING": "http://localhost:8095",
        "CB_OI_USERNAME": "Administrator",
        "CB_OI_PASSWORD": "password"
      }
    }
  }
}

См. Инструменты Operational Insights выше для списка инструментов и примечание о трёх именах инструментов, общих с операционным сервером.

Оба сервера используют единую запись в MCP Registry, io.github.couchbase/mcp-server-couchbase, опубликованную из server.json. В списке есть отдельная запись пакета для каждого сервера (PyPI и Docker). Каждая запись передаёт свою подкоманду (operational или operational-insights) и объявляет только аргументы и переменные окружения этого сервера.

Режим транспорта Streamable HTTP

MCP-сервер можно запустить в режиме транспорта Streamable HTTP, который позволяет нескольким клиентам подключаться к одному экземпляру сервера через HTTP. Проверьте, поддерживает ли ваш MCP-клиент транспорт streamable http, прежде чем пытаться подключиться к MCP-серверу в этом режиме.

Примечание: Авторизация OAuth 2.1 поддерживается на этом транспорте. См. Авторизация OAuth 2.1. Без настройки OAuth конечная точка HTTP не аутентифицирована.

Использование

По умолчанию MCP-сервер будет работать на порту 8000, но это можно настроить с помощью переменной окружения --port или CB_MCP_PORT.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=http

Сервер будет доступен по адресу http://localhost:8000/mcp. Это можно использовать в MCP-клиентах, поддерживающих режим транспорта streamable http, таких как Cursor.

Конфигурация MCP-клиента

{
  "mcpServers": {
    "couchbase-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Режим транспорта SSE

Существует возможность запустить MCP-сервер в режиме транспорта Server-Sent Events (SSE).

Примечание: Режим SSE устарел в MCP. Мы поддерживаем Streamable HTTP.

SSE: Использование

По умолчанию MCP-сервер будет работать на порту 8000, но это можно настроить с помощью переменной окружения --port или CB_MCP_PORT.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=sse

Сервер будет доступен по адресу http://localhost:8000/sse. Это можно использовать в MCP-клиентах, поддерживающих режим транспорта SSE, таких как Cursor.

SSE: Конфигурация MCP-клиента

{
  "mcpServers": {
    "couchbase-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Авторизация OAuth 2.1

При работе с --transport=http MCP-сервер может действовать как сервер ресурсов OAuth 2.1: он проверяет входящие bearer JWT-токены против JWKS вашего поставщика удостоверений. Он не зависит от поставщика (любой поставщик OAuth 2.1 / OIDC, публикующий JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra и т. д.) и не выдаёт токены и не управляет пользователями. Настройки OAuth игнорируются на stdio.

OAuth настраивается с помощью переменных CB_MCP_OAUTH_*, перечисленных в Дополнительной конфигурации:

• OAuth активируется только когда заданы все три переменные CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER и CB_MCP_OAUTH_JWT_AUDIENCE; задание только некоторых из них приводит к ошибке при запуске.
• Задание CB_MCP_OAUTH_MCP_BASE_URL дополнительно публикует метаданные защищённого ресурса RFC 9728, чтобы клиенты с поддержкой PRM могли обнаружить сервер авторизации.
• Доступ ограничен двумя областями, считываемыми из утверждения scope/scp токена: couchbase-mcp:read (инструменты чтения, включая SQL++) и couchbase-mcp:write (инструменты записи: мутации KV, управление областями/коллекциями и управление индексами). Полный доступ требует обеих областей. Если ваш IdP не может выдавать эти канонические метки, переопределите их с помощью CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http \
  --oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
  --oauth-issuer='https://auth.example.com/' \
  --oauth-audience='couchbase-mcp-server' \
  --oauth-mcp-base-url='<public_base_url_of_this_server>'

Полные сведения см. в документации.

Docker-образ

MCP-сервер также можно собрать и запустить как Docker-контейнер. Готовые образы можно найти на DockerHub или загрузить через docker pull docker.io/couchbase/mcp-server:latest.

Кроме того, мы являемся частью Docker MCP Catalog.

Сборка образа

docker build -t mcp/couchbase-src .

docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mcp/couchbase-src .

# Build with default image name (mcp/couchbase-src)
./build.sh

# Build with custom image name
./build.sh my-custom/image-name

# View git commit hash in image
docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase-src:latest

# View all metadata labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest

Запуск

MCP-сервер можно запустить с использованием переменных окружения для настройки параметров Couchbase. Переменные окружения такие же, как описано в разделе Дополнительная конфигурация.

Независимый Docker-контейнер

docker run --rm -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
  -e CB_MCP_READ_ONLY_MODE='<true|false>' \
  -e CB_MCP_CONFIRMATION_REQUIRED_TOOLS='delete_document_by_id' \
  -e CB_MCP_PORT=9001 \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 9001:9001 \
  mcp/couchbase-src

Переменные окружения CB_MCP_PORT и CB_MCP_HOST применимы только в случае режимов HTTP-транспорта, таких как http и sse.

Docker: Конфигурация MCP-клиента

Docker-образ можно использовать в режиме транспорта stdio со следующей конфигурацией.

{
  "mcpServers": {
    "couchbase-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_user>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "mcp/couchbase-src"
      ]
    }
  }
}

Примечания

• Значение couchbase_connection_string зависит от того, работает ли сервер Couchbase на том же хост-компьютере, в другом Docker-контейнере или на удалённом хосте. Если ваш сервер Couchbase работает на вашем хост-компьютере, ваша строка подключения, скорее всего, будет иметь вид couchbase://host.docker.internal. Подробности см. в документации docker.
• Вы можете указать сеть контейнера с помощью опции --network=<your_network>. Выбранная сеть зависит от вашего окружения; по умолчанию используется bridge. Подробности см. в разделе сетевые драйверы в docker.

Риски, связанные с LLM

• Использование больших языковых моделей и подобных технологий связано с рисками, включая возможность неточных или вредных результатов.
• Couchbase не проверяет и не оценивает качество или точность таких результатов, и такие результаты могут не отражать мнение Couchbase.
• Вы несёте единоличную ответственность за решение об использовании больших языковых моделей и связанных технологий, а также за соблюдение любых условий лицензий, условий использования и политик вашей организации, регулирующих их использование.

Сбор данных об использовании

Этот продукт автоматически собирает данные об использовании и производительности (такие как название продукта и версия) и информацию о браузере (такую как IP-адрес) (совместно «Данные об использовании»). Couchbase использует Данные об использовании, а также другие данные, которые вы можете предоставить Couchbase (такие как ваше имя пользователя или адрес электронной почты), для разработки и улучшения наших продуктов, а также для информирования наших программ продаж и маркетинга. Мы не получаем доступ и не собираем данные, которые вы храните в продуктах Couchbase. Мы используем Данные об использовании для понимания общих моделей использования и делаем наши продукты более полезными для вас. Для получения дополнительной информации о том, как Couchbase собирает, защищает и обрабатывает информацию, обратитесь к Политике конфиденциальности Couchbase, доступной по адресу https://www.couchbase.com/privacy-policy.

Советы по устранению неполадок

• Убедитесь, что путь к репозиторию вашего MCP-сервера указан правильно в конфигурации, если вы запускаете из исходного кода.
• Проверьте, что строка подключения к Couchbase, имя пользователя базы данных, пароль или пути к сертификатам указаны правильно.
• Если вы используете Couchbase Capella, убедитесь, что кластер доступен с машины, на которой работает MCP-сервер.
• Проверьте, что у пользователя базы данных есть соответствующие разрешения для доступа хотя бы к одному bucket.
• Убедитесь, что менеджер пакетов uv правильно установлен и доступен. Возможно, потребуется указать абсолютный путь к uv/uvx в поле command в конфигурации.
• Проверьте журналы на наличие ошибок или предупреждений, которые могут указывать на проблемы с MCP-сервером. Расположение журналов зависит от вашего MCP-клиента.
• Если вы наблюдаете проблемы при запуске MCP-сервера из исходного кода после обновления локального репозитория MCP-сервера, попробуйте выполнить uv sync для обновления зависимостей.

Интеграционное тестирование

Мы предоставляем высокоуровневые интеграционные тесты MCP для проверки того, что сервер предоставляет ожидаемые инструменты и что их можно вызывать против демонстрационного кластера Couchbase.

1. Экспортируйте учётные данные демонстрационного кластера:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • Необязательно: CB_MCP_TEST_BUCKET (bucket для проверки во время тестов)
   • Необязательно, для собственных тестов сервера Operational Insights: CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD. Эти тесты автоматически пропускаются (не завершаются с ошибкой), когда переменные не заданы.
2. Запустите тесты:

uv run --extra dev pytest tests/integration -v

Часто задаваемые вопросы

Что такое Couchbase MCP Server? Это самостоятельно размещаемая реализация Model Context Protocol, которая позволяет ИИ-ассистентам и агентам (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie и любому другому MCP-клиенту) запрашивать и, при желании, изменять данные в кластере Couchbase с помощью естественного языка.

Как подключить Claude Desktop к Couchbase? Установите сервер с помощью uvx couchbase-mcp-server (или запустите его из исходного кода или Docker), затем добавьте его конфигурацию в claude_desktop_config.json Claude Desktop, как показано в Конфигурации. Перезапустите Claude Desktop, и он подхватит новые инструменты.

Могу ли я использовать это с Couchbase Capella? Да. Та же конфигурация CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD (или сертификат mTLS) работает как для Couchbase Capella, так и для самостоятельно управляемых кластеров Couchbase Server.

Безопасно ли позволять ИИ-агенту записывать в мою базу данных? По умолчанию CB_MCP_READ_ONLY_MODE имеет значение true, поэтому все операции записи — upsert/insert/replace/delete документов и изменяющие данные операторы SQL++ — отключены, и инструменты записи даже не загружаются. Вы также можете отключить отдельные инструменты (см. Отключение инструментов) или требовать явного подтверждения пользователя перед выполнением конкретных инструментов (см. Запрос/Подтверждение). Контроль на уровне инструментов направляет поведение LLM; разрешения RBAC вашего пользователя Couchbase остаются реальной границей безопасности.

Могу ли я выполнять запросы на естественном языке к своим данным, не написав SQL++ самостоятельно? Да — задайте вашему ИИ-ассистенту вопрос на простом английском (например, «покажи мне 10 самых последних заказов на сумму более $100»), и он сможет перевести его в запрос SQL++ с помощью инструмента run_sql_plus_plus_query. Вы также можете попросить ассистента explain_sql_plus_plus_query запрос или обратиться к советнику по индексам за рекомендациями. В чём разница между транспортами STDIO, Streamable HTTP и SSE? STDIO предназначен для одного локального MCP-клиента (например, Claude Desktop), который запускает сервер как подпроцесс. Streamable HTTP позволяет нескольким клиентам совместно использовать один запущенный экземпляр сервера через HTTP и поддерживает OAuth 2.1. SSE — это более старый HTTP-транспорт, который теперь объявлен устаревшим в спецификации MCP в пользу Streamable HTTP — см. Streamable HTTP Transport Mode.

Официально ли это поддерживается Couchbase? Этот проект поддерживается сообществом Couchbase — см. Support Policy. Корпоративная поддержка доступна отдельно через Couchbase AI Data Plane.

Участие в разработке

Мы приветствуем вклад сообщества! Хотите ли вы исправить ошибки, добавить функции или улучшить документацию — ваша помощь ценится.

Если вам нужна помощь, вы нашли ошибку или хотите предложить улучшения, лучшее место для этого — прямо здесь, открыв issue на GitHub.

Для разработчиков

Если вы заинтересованы в написании кода или настройке среды разработки:

📖 См. CONTRIBUTING.md для подробных инструкций по настройке для разработчиков, включая:

• Настройку среды разработки с uv
• Линтинг и форматирование кода с помощью Ruff
• Установку pre-commit хуков
• Обзор структуры проекта
• Рабочий процесс и практики разработки

Быстрый старт для контрибьюторов

# Clone and setup
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run linting
./scripts/lint.sh

📢 Политика поддержки

Мы искренне ценим ваш интерес к этому проекту! Этот проект поддерживается сообществом Couchbase, что означает, что он не поддерживается официально нашей службой поддержки. Однако наши инженеры активно следят за этим репозиторием и поддерживают его, и будут стараться решать проблемы по мере возможностей.

Наш портал поддержки не может помочь с запросами, связанными с этим проектом, поэтому мы просим все вопросы оставлять в рамках GitHub.

Ваше сотрудничество помогает нам всем двигаться вперёд вместе — спасибо!