Couchbase

Couchbase MCP Server

Couchbase MCP Server 是一个自托管的 MCP 服务器，允许 AI 代理连接并交互 Couchbase 集群中的数据，无论是在 Capella 上托管还是自管理。它提供跨类别的工具，包括集群健康、数据模式、键值、查询和性能——并通过只读模式和细粒度工具禁用提供安全控制。它支持 STDIO 和 Streamable HTTP 传输。

Couchbase MCP 服务器以 Python 包索引（PyPI）包的形式分发，也可通过 Docker 分发。 通过许可 Couchbase AI Data Plane 可获得 Couchbase MCP 服务器的企业支持，该许可还包含 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 运行

我们为 MCP 服务器发布了预构建的 PyPI 包。

使用预构建包为 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、查询、作用域/集合管理和索引管理）均被禁用。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 时：KV、作用域/集合管理和索引写入工具会被加载，并允许 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 工具使用 SQL++ DML 语句（INSERT、UPDATE、DELETE、MERGE）进行，除非：

• CB_MCP_READ_ONLY_MODE 设置为 true（默认），或者
• 数据库用户缺乏数据修改所需的 RBAC 权限

最佳实践： 始终在您的 Couchbase 用户凭据上配置适当的 RBAC 权限作为主要安全措施。将工具禁用作为引导 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 是每个级别文件轮转的全局大小（以 MB 为单位）。使用 CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB（ERROR/WARNING/INFO/DEBUG）覆盖各个级别，同样以 MB 为单位，未设置时继承全局值。大小为 0（全局或按级别）无效，将回退到默认值（1 MB）并发出启动警告。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 服务器之前，请检查你的 MCP 客户端 是否支持 streamable http 传输。

注意：此传输支持 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 上可用。这可用于支持 streamable http 传输模式的 MCP 客户端，例如 Cursor。

MCP 客户端配置

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

SSE 传输模式

可以选择以 Server-Sent Events (SSE) 传输模式运行 MCP 服务器。

注意：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 上可用。这可用于支持 SSE 传输模式的 MCP 客户端，例如 Cursor。

SSE：MCP 客户端配置

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

OAuth 2.1 授权

当使用 --transport=http 运行时，MCP 服务器可以充当 OAuth 2.1 资源服务器：它会根据你的身份提供商的 JWKS 验证传入的 bearer JWT。它与提供商无关（任何发布 JWKS 的 OAuth 2.1 / OIDC 提供商 — Auth0、Okta、Keycloak、AWS Cognito、Microsoft Entra 等），并且不签发令牌或管理用户。OAuth 设置在 stdio 上被忽略。

OAuth 使用 Additional Configuration 中列出的 CB_MCP_OAUTH_* 变量进行配置：

• 仅当 CB_MCP_OAUTH_JWT_JWKS_URI、CB_MCP_OAUTH_JWT_ISSUER 和 CB_MCP_OAUTH_JWT_AUDIENCE 全部设置时，OAuth 才会激活；仅设置其中一部分将在启动时失败。
• 设置 CB_MCP_OAUTH_MCP_BASE_URL 还会发布 RFC 9728 Protected Resource Metadata，以便支持 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 设置。环境变量与 Additional Configuration section 中描述的相同。

独立 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 和 sse 等 HTTP 传输模式。

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 如何收集、保护和处​​理信息的更多信息，请参阅可在 https://www.couchbase.com/privacy-policy. 查看的 Couchbase 隐私政策。

故障排除提示

• 如果从源代码运行，请确保配置中 MCP 服务器仓库的路径正确。
• 请验证您的 Couchbase 连接字符串、数据库用户名、密码或证书路径是否正确。
• 如果使用 Couchbase Capella，请确保集群可从运行 MCP 服务器的机器访问。
• 检查数据库用户是否具有访问至少一个存储桶的适当权限。
• 确认 uv 包管理器已正确安装且可访问。您可能需要在配置的 command 字段中提供 uv/uvx 的绝对路径。
• 检查日志中是否有任何可能表明 MCP 服务器存在问题的错误或警告。日志的位置取决于您的 MCP 客户端。
• 如果在更新本地 MCP 服务器仓库后从源代码运行 MCP 服务器时遇到问题，请尝试运行 uv sync 来更新依赖项。

集成测试

我们提供高级 MCP 集成测试，以验证服务器是否公开了预期的工具，以及这些工具是否可以针对演示 Couchbase 集群调用。

1. 导出演示集群凭据：
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • 可选：CB_MCP_TEST_BUCKET（测试期间要探测的存储桶）
2. 运行测试：

uv run pytest tests/ -v

👩‍💻 贡献

我们欢迎社区的贡献！无论您想修复错误、添加功能还是改进文档，我们都非常感谢您的帮助。

如果您需要帮助、发现了错误或想贡献改进，最好的地方就是这里——通过打开 GitHub issue。

面向开发者

如果您有兴趣贡献代码或搭建开发环境：

📖 请参阅 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 内。

您的协作帮助我们共同前进——谢谢！