Couchbase

Couchbase MCP Server

Couchbase MCP Server — это самостоятельно размещаемый MCP-сервер, который позволяет AI-агентам подключаться к кластерам Couchbase и взаимодействовать с данными в них, независимо от того, размещены ли они на Capella или управляются самостоятельно. Он предоставляет инструменты по категориям: здоровье кластера, схема данных, Key-Value, запросы и производительность — с механизмами контроля безопасности через режим только для чтения и детальным отключением инструментов. Поддерживаются транспорты 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.

Функции/Инструменты

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

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

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

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

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

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

• 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, управление scope/collection и индексом) отключены. Инструменты записи KV (upsert, insert, replace, delete, sub-document mutate), инструменты записи управления scope/collection (create_scope, create_collection, delete_scope, delete_collection) и инструменты записи индексов (create_index, build_index, drop_index) не загружаются и не будут доступны LLM, а SQL++ запросы, изменяющие данные или структуру, блокируются.
• Когда задано false: Инструменты записи KV, управления scope/collection и индексами загружаются, и SQL++ запросы на изменение данных/структуры разрешены.

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

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

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

Вы можете отключить определённые инструменты, чтобы предотвратить их загрузку и предоставление 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 с использованием SQL++ DML-операторов (INSERT, UPDATE, DELETE, MERGE), если только:

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

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

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

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

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

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

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

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

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

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

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

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

MCP-сервер может работать в режиме транспортного протокола Streamable HTTP, который позволяет нескольким клиентам подключаться к одному экземпляру сервера через HTTP. Проверьте, поддерживает ли ваш MCP-клиент transport 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-совместимые клиенты могли обнаружить сервер авторизации.
• Доступ ограничен двумя областями (scopes), считываемыми из утверждения 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 для проверки во время тестов)
2. Запустите тесты:

uv run pytest tests/ -v

👩‍💻 Вклад в проект

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

Если вам нужна помощь, вы нашли ошибку или хотите внести улучшения, лучшее место для этого — открыть вопрос на 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.

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