Couchbase

Couchbase MCP 服务器

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

Couchbase MCP 服务器以 Python 包索引 (PyPI) 包和 Docker 镜像的形式分发。 Couchbase MCP 服务器的企业支持可通过许可 Couchbase AI Data Plane 获得，该许可还授权使用 Couchbase Agent Memory 和 Couchbase Agent Catalog 并获得企业支持。

完整文档请访问 mcp-server.couchbase.com。

功能/工具

集群设置与健康工具

数据模型与模式发现工具

文档键值操作工具

查询和索引工具

查询性能分析工具

先决条件

• 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（默认）时：所有写操作（键值和查询）都被禁用。键值写入工具（更新插入、插入、替换、删除）不会被加载，并且对 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 工具使用 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 时，会在 CB_MCP_LOG_FILE 设置的路径下为每个级别写入一个文件（例如 mcp_server.info.log 和 mcp_server.error.log）。

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

有关更多详细信息，请参阅文档。

客户端特定配置

可流式 HTTP 传输模式

MCP 服务器可以在可流式 HTTP 传输模式下运行，这允许多个客户端通过 HTTP 连接到同一个服务器实例。 在尝试以此模式连接到 MCP 服务器之前，请检查您的 MCP 客户端是否支持可流式 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 上可用。这可以在支持可流式 HTTP 传输模式的 MCP 客户端（如 Cursor）中使用。

MCP 客户端配置

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

SSE 传输模式

可以选择在服务器发送事件 (SSE) 传输模式下运行 MCP 服务器。

注意：SSE 模式已被 MCP 弃用。我们支持可流式 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 验证传入的持有者 JWT。它与提供商无关（任何发布 JWKS 的 OAuth 2.1 / OIDC 提供商——Auth0、Okta、Keycloak、AWS Cognito、Microsoft Entra 等），并且不颁发令牌或管理用户。在 stdio 上，OAuth 设置将被忽略。

OAuth 通过附加配置中列出的 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 受保护资源元数据，以便支持 PRM 的客户端可以发现授权服务器。
• 访问由从令牌的 scope/scp 声明中读取的两个范围控制：couchbase-mcp:read（读取工具，包括 SQL++）和 couchbase-mcp:write（KV 变更工具）。完全访问需要两者兼具。

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 目录的一部分。

构建镜像

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 和 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 的观点。
• 您需自行决定是否使用大型语言模型及相关技术，并负责遵守任何许可条款、使用条款以及您所在组织关于使用这些技术的政策。

故障排除提示

• 如果从源代码运行，请确保配置中 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 进行代码检查和格式化
• 安装预提交钩子
• 项目结构概览
• 开发工作流程和实践

贡献者快速入门

# 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 内。

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