Couchbase

Couchbase MCP 服务器

Couchbase MCP 服务器是一个自托管的 Model Context Protocol (MCP) 服务器，它将 AI 代理和基于 LLM 的助手（Claude、Cursor、Windsurf、VS Code Copilot 以及其他 MCP 客户端）连接到 Couchbase 集群中的数据，无论这些数据托管在 Capella 上还是自管理环境中。MCP 是一个开放标准，允许 AI 助手调用工具并查询外部数据源；该服务器为 Couchbase 实现了这一标准，因此 AI 代理可以使用自然语言而非手写代码来检查您的集群、运行 SQL++ 查询、读写文档以及分析查询性能。

它提供了跨类别的工具，包括集群健康、数据模式、键值、查询和性能——并通过只读模式（默认开启）和细粒度的工具禁用功能提供安全控制，这样您可以让 AI 代理探索和查询数据，而无需担心意外的写入操作。它支持 STDIO 和流式 HTTP 传输。

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

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

如需完整文档，请访问 docs.couchbase.com/mcp-server。

目录

• 为什么选择 Couchbase MCP 服务器
• 示例提示
• 功能/工具
• 前提条件
• 配置
• 运营洞察服务器
• 流式 HTTP 传输模式
• SSE 传输模式
• OAuth 2.1 授权
• Docker 镜像
• 使用数据收集
• 故障排除提示
• 集成测试
• 常见问题
• 贡献
• 支持政策

为什么选择 Couchbase MCP 服务器

• 默认安全 — 除非您明确设置 CB_MCP_READ_ONLY_MODE=false，否则写入操作（文档 upsert/insert/delete 以及修改数据的 SQL++ 查询）将被阻止，并且可以禁用单个工具或将其置于用户确认之后。
• 适用于 Capella 和自管理集群 — 相同的配置可连接到 Couchbase Capella（完全托管）或自托管的 Couchbase Server 集群。
• 支持 RBAC — 工具禁用是引导 LLM 行为的便捷层；底层 Couchbase 用户的基于角色的访问控制仍然是权威的安全边界。
• 生产级传输 — 通过 STDIO 运行以支持本地桌面客户端，或通过流式 HTTP（可选 OAuth 2.1（JWT/JWKS，提供商无关——Auth0、Okta、Keycloak、Entra、Cognito 等））运行以支持共享/远程部署。
• 任何 MCP 客户端 — 已通过 Claude Desktop、Cursor、Windsurf、VS Code 和 JetBrains AI Assistant/Junie 测试；适用于任何实现 MCP 规范 的客户端。

示例提示

服务器连接后，您可以通过 AI 助手用自然语言与 Couchbase 集群对话。例如：

• “这个集群中有哪些 bucket、scope 和 collection，orders collection 的模式是什么？”
• “运行一个 SQL++ 查询，在 users collection 中查找最近的 10 个文档 where status = 'active'。”
• “过去一小时内这个集群上最慢的 5 个查询是什么，其中是否有缺少覆盖索引的？”
• “检查这个集群是否健康，并告诉我哪些服务正在运行。”
• “在 products collection 中插入一个新文档，包含以下字段：...” （需要 CB_MCP_READ_ONLY_MODE=false）

功能/工具

此发行版附带两个服务器：运营服务器（默认——见下方表格）通过 couchbase SDK 与常规 Couchbase 集群通信，而 运营洞察 服务器（其自己的表格在下方）通过 couchbase-operational-insights SDK 与运营洞察集群通信。

集群设置与健康工具

数据模型与模式发现工具

文档 KV 操作工具

查询与索引工具

全文搜索（FTS）工具

需要 Couchbase Server 7.6+ 和 Search 服务。这些工具不支持向量搜索（请参阅单独的向量搜索工具）。

查询性能分析工具

运营洞察工具

由单独的 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 运行

我们为 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 客户端进行服务器配置

这是针对 Claude Desktop、Cursor、Windsurf Editor 等 MCP 客户端的通用配置。

{
  "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、子文档修改；作用域/集合管理：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 工具使用 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

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

客户端特定配置

运维洞察服务器

除了默认的 operational 服务器（上述每个部分描述的服务器）之外，此发行版还附带第二个服务器，用于 运维洞察 集群，使用单独的 couchbase-operational-insights SDK。它是与常规 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 是 HTTP(S) URL，而不是 couchbase:// 连接字符串 — 例如，对于本地运维洞察服务器，使用 http://localhost:8095，对于 Capella，使用 https://<host>:18095。这是将此服务器指向集群时最常见的错误配置。

所有其他标志（--read-only-mode、--transport、--host、--port、 --disabled-tools、--confirmation-required-tools、--log-*、 --oauth-*）与操作服务器的相同 — 参见 Additional Configuration for MCP Server — 但 端口（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 tools 了解 工具列表，以及其中关于与操作服务器共享的三个工具名称的说明。

两个服务器共享一个 MCP Registry 列表，io.github.couchbase/mcp-server-couchbase，发布自 server.json。该列表为每个服务器提供单独的包条目（PyPI 和 Docker）。每个条目传递其子命令（operational 或 operational-insights），并仅声明该服务器的参数和环境变量。

Streamable HTTP 传输模式

MCP 服务器可以在 Streamable HTTP 传输模式下运行，该模式允许多个客户端通过 HTTP 连接到同一服务器实例。 在尝试以该模式连接到 MCP 服务器之前，请检查您的 MCP 客户端 是否支持 streamable http 传输。

注意：此传输支持 OAuth 2.1 授权。参见 OAuth 2.1 Authorization。未配置 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 受保护资源元数据，以便支持 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 传输模式（如 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 如何收集、保护和处​​理信息的更多信息，请参阅可在 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（测试期间要探测的存储桶）
   • 可选，用于 Operational Insights 服务器 的 自身测试：CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD。 这些测试在未设置时自动跳过（不失败）。
2. 运行测试：

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

常见问题解答

什么是 Couchbase MCP 服务器？ 它是 Model Context Protocol 的自托管实现，允许 AI 助手和代理（Claude、Cursor、Windsurf、VS Code Copilot、JetBrains AI Assistant/Junie 以及任何其他 MCP 客户端）使用自然语言查询，并可选择修改 Couchbase 集群中的数据。

如何将 Claude Desktop 连接到 Couchbase？ 使用 uvx couchbase-mcp-server 安装服务器（或从源代码或 Docker 运行），然后按照 Configuration 中的说明将其配置添加到 Claude Desktop 的 claude_desktop_config.json。重启 Claude Desktop，它将获取新工具。

我可以将其与 Couchbase Capella 一起使用吗？ 可以。相同的 CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD（或 mTLS 证书）配置适用于 Couchbase Capella 和自管理 Couchbase Server 集群。

让 AI 代理写入我的数据库安全吗？ 默认情况下，CB_MCP_READ_ONLY_MODE 为 true，因此所有写操作 — 文档 upsert/insert/replace/delete 和数据修改 SQL++ 语句 — 都被禁用，写工具甚至不会加载。您还可以禁用单个工具（参见 Disabling Tools）或要求在特定工具运行前获得明确的用户确认（参见 Elicitation/Confirmation）。工具级控制指导 LLM 行为；您的 Couchbase 用户的 RBAC 权限仍然是真正的安全边界。

我可以自己对数据运行自然语言查询而无需编写 SQL++ 吗？ 可以 — 用简单的英语向您的 AI 助手提问（例如"显示最近 10 个超过 100 美元的订单"），它可以使用 run_sql_plus_plus_query 工具将其转换为 SQL++ 查询。您还可以要求助手 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 传输模式。

这是否由 Couchbase 官方支持？ 该项目由 Couchbase 社区维护——参见 支持政策。企业支持可通过 Couchbase AI 数据平面 单独获取。

贡献

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

如果您需要帮助、发现了错误，或想贡献改进，最好的方式就是在这里——通过 开启一个 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 内进行。

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