适合谁
- 需要在 AI 客户端（Claude Desktop、Cursor、Windsurf、VS Code、JetBrains IDE 等）中安全访问 Couchbase 数据的开发者与数据团队
- 已在使用 Couchbase（Capella 或自管理）并希望引入 LLM 辅助查询与分析的团队
C
72FMRS · B
由 Couchbase 官方维护、功能完备的数据库 MCP 服务器：覆盖集群健康、模式发现、KV 操作、SQL++ 查询、索引管理与性能分析，默认只读、支持工具禁用/执行确认/OAuth 2.1，配置项丰富且文档详尽。适合 Couchbase 用户在主流 MCP 客户端中引入 AI 数据操作，但需牢记 RBAC 才是权威安全边界。
Couchbase 官方维护的自托管 MCP 服务器，允许 AI 代理连接 Capella 或自管理的 Couchbase 集群并操作其中的数据。提供集群健康、数据模式、键值（KV）、查询与性能分析五大类工具，默认启用只读模式，并支持细粒度工具禁用、执行前确认（需客户端支持 elicitation）、OAuth 2.1 授权（HTTP 传输）与详细的日志配置。通过 PyPI 包（couchbase-mcp-server）、Docker 镜像或源码运行，支持 STDIO 与 Streamable HTTP（及已弃用的 SSE）传输。
工具能力
get_server_configuration_status
无需连接集群即可获取服务器状态与配置（只读模式、禁用/需确认工具、OAuth 设置、日志配置）
test_cluster_connection
通过连接集群验证凭据
get_cluster_health_and_services
获取集群健康状态及所有运行中的服务列表
get_buckets_in_cluster
获取集群中所有存储桶列表
get_scopes_in_bucket
获取指定存储桶中所有作用域列表
get_collections_in_scope
获取指定作用域和存储桶中所有集合列表（需要集群具有查询服务）
get_scopes_and_collections_in_bucket
获取指定存储桶中所有作用域和集合
get_schema_for_collection
获取集合的结构/模式
create_scope
在存储桶中创建新作用域（Couchbase Server 7.6+ 及 Capella），只读模式下默认禁用
create_collection
在现有作用域中创建新集合（Couchbase Server 7.6+ 及 Capella），只读模式下默认禁用
delete_scope
删除作用域及其所有集合——不可恢复，只读模式下默认禁用
delete_collection
删除集合及其所有文档——不可恢复，只读模式下默认禁用
get_document_by_id
按文档 ID 从指定的作用域和集合中获取文档
sub_document_lookup_in
按路径查找文档的部分内容（特定字段、存在性检查、数组/对象计数），无需获取整个文档
upsert_document_by_id
按 ID 将文档 upsert 到指定的作用域和集合，只读模式下默认禁用
insert_document_by_id
按 ID 插入新文档（若文档已存在则失败），只读模式下默认禁用
replace_document_by_id
按 ID 替换现有文档（若文档不存在则失败），只读模式下默认禁用
delete_document_by_id
按 ID 从指定的作用域和集合中删除文档，只读模式下默认禁用
sub_document_mutate_in
按路径修改现有文档的部分内容（upsert、insert、replace、remove、数组操作、计数器），无需重写整个文档，只读模式下默认禁用
list_indexes
列出集群中所有索引及其定义，可按桶、作用域、集合和索引名过滤，可返回原始索引统计
get_index_advisor_recommendations
从 Couchbase Index Advisor 获取针对给定 SQL++ 查询的索引建议
create_index
在集合上创建标量（非向量）GSI 二级索引，默认延迟创建，需随后调用 build_index，只读模式下默认禁用
build_index
触发构建集合上所有延迟索引，只读模式下默认禁用
drop_index
从集合中删除 GSI 索引（标量或向量），只读模式下默认禁用
run_sql_plus_plus_query
在指定作用域上运行 SQL++ 查询；查询自动限定到指定的桶和作用域；只读模式（默认）下修改数据的查询会被阻止
explain_sql_plus_plus_query
为 SQL++ 查询生成并评估 EXPLAIN 计划，返回查询元数据、提取的计划及评估结果
get_longest_running_queries
按平均服务时间获取运行时间最长的查询
get_most_frequent_queries
获取执行最频繁的查询
get_queries_with_largest_response_sizes
获取响应大小最大的查询
get_queries_with_large_result_count
获取结果数量最多的查询
get_queries_using_primary_index
获取使用主索引的查询（潜在性能问题）
get_queries_not_using_covering_index
获取未使用覆盖索引的查询
get_queries_not_selective
获取选择性不足的查询（索引扫描返回的文档远多于最终结果）
安装接入
前置条件：Python 3.10+、运行中的 Couchbase 集群（推荐 Capella 免费层）、已安装 uv、以及 Claude Desktop 或 Cursor 等 MCP 客户端。PyPI 方式：在客户端配置的 mcpServers 中添加 command 为 uvx、args 为 ["couchbase-mcp-server"]，并在 env 中设置 CB_CONNECTION_STRING、CB_USERNAME、CB_PASSWORD（mTLS 则使用 CB_CLIENT_CERT_PATH 和 CB_CLIENT_KEY_PATH）。源码方式：克隆仓库后用 uv --directory <仓库路径> run src/mcp_server.py。也可使用 Docker 镜像 docker.io/couchbase/mcp-server。
claude_desktop_config.json
{"mcpServers":{"couchbase":{"command":"uvx","args":["couchbase-mcp-server"],"env":{"CB_CONNECTION_STRING":"couchbases://connection-string","CB_USERNAME":"username","CB_PASSWORD":"password"}}}}
选型与风险
不适合谁
- 需要完全无人值守写入生产数据库且未评估风险的场景（默认只读模式会阻止写入）
- 不使用 Couchbase 或无运行集群的用户
- 需要官方支持门户协助的场景（此为社区维护项目，仅通过 GitHub 提供支持）
所需权限
- 通过环境变量或命令行参数提供 Couchbase 连接字符串及基本认证的用户名/密码，或 mTLS 的客户端证书与密钥路径
- 非 Capella 集群使用自签名/不受信任证书时需提供 CA 根证书路径
- 数据库用户需具备访问目标存储桶的 RBAC 权限，这是权威安全控制
风险与副作用
- 默认 CB_MCP_READ_ONLY_MODE=true 禁用所有写操作；设为 false 后 LLM 可修改/删除文档、作用域、集合和索引
- 仅禁用工具不足以保证安全：SQL++ DML 仍可通过 run_sql_plus_plus_query 修改数据，必须配合只读模式或恰当的 RBAC 权限
- delete_scope/delete_collection 会永久删除数据
- HTTP 传输在未配置 OAuth 时端点无认证
- LLM 输出可能不准确，Couchbase 不审查其质量，使用者需自行承担责任
- 产品会自动收集使用与性能数据（如产品版本、IP 地址），详见 Couchbase 隐私政策
常见排障
- 确认从源码运行时配置中的仓库路径正确（注意末尾斜杠）
- 核对连接字符串、用户名、密码或证书路径是否正确
- 若使用 Capella，确保集群对运行 MCP 服务器的机器 IP 可访问（允许列表）
- 确认数据库用户至少对一个存储桶有权限
- 确认 uv 已正确安装且可访问，必要时在配置中提供 uv/uvx 的绝对路径
- 查看 MCP 客户端日志排查错误；从源码更新后可运行 uv sync 同步依赖
- 通过 uvx couchbase-mcp-server --version 查看服务器版本
使用场景
用自然语言查询 Couchbase 数据并执行文档 CRUD 操作
探索集群结构与数据模式（桶、作用域、集合、Schema）
分析查询性能瓶颈并获取索引建议
创建和管理 GSI 二级索引
支持客户端
Claude Desktop完整支持
Cursor完整支持
Windsurf Editor完整支持
VS Code完整支持
JetBrains IDEs完整支持