Couchbase MCP Server

官方

让 AI 代理安全连接并操作 Couchbase 集群数据

分类: 数据库第 7 / 58
Stars: ★ 34 热门
传输方式: stdio（本地进程） · SSE · Streamable HTTP
运行环境: Python 3.10+ · Docker
凭据: 需要 API Key / 凭据
许可证: Apache-2.0
最近提交: 7 天前
工具数: 33

72FMRS · B

由 Couchbase 官方维护、功能完备的数据库 MCP 服务器：覆盖集群健康、模式发现、KV 操作、SQL++ 查询、索引管理与性能分析，默认只读、支持工具禁用/执行确认/OAuth 2.1，配置项丰富且文档详尽。适合 Couchbase 用户在主流 MCP 客户端中引入 AI 数据操作，但需牢记 RBAC 才是权威安全边界。

最强项 · 文档质量 18/20 最弱项 · 可靠性 11/20

可靠性

11/20

安全与权限

16/20

维护活跃度

13/20

文档质量

18/20

安装易用性

14/20

查看各项评分依据

可靠性 11/20: manifest 与 README 中的工具列表、参数命名（如 CB_MCP_READ_ONLY_MODE 对应的写操作工具不加载）高度一致，命令行参数与环境变量一一对应，说明文档具有内部自洽性；README 提到集成测试目录 tests/ 及 'uv run pytest tests/ -v'，但该测试依赖真实 Couchbase 集群凭据才能运行，材料中未提供 CI workflow 文件或测试通过的可验证证据。按静态评审规则，未见可验证的 CI+测试证据，可靠性分数不应超过12分，因此给出11分：happy path 描述可信，但错误处理、边界情况和真实执行证据不足。
安全与权限 16/20: 默认 CB_MCP_READ_ONLY_MODE=true，写操作工具（KV写、scope/collection管理、索引管理）默认不加载，是较强的默认最小权限设计；提供基于 elicitation 的高危操作二次确认机制（CB_MCP_CONFIRMATION_REQUIRED_TOOLS）；支持工具级禁用；HTTP 传输下支持 OAuth 2.1 + JWKS 校验及基于 scope 的读写权限区分；文档明确警告工具禁用不能替代数据库 RBAC 权限控制，敦促以 RBAC 为主要防线；密码字段在 manifest 中标记为 isSecret，日志文档提及配置快照会做 redacted 处理。扣分点：HTTP 传输在未配置 OAuth 时明确是'unauthenticated'（虽然文档已明确披露，但仍是可被误用的默认风险点）；证书路径类变量未标记为 secret（相对次要）。整体未触及红线，安全设计与披露较为完整，故给16分。
维护活跃度 13/20: 仓库采用 Apache-2.0 许可证，非 archived 状态，34 星、6个未解决 issue，版本号为 1.0.2rc1 显示仍在积极发布候选版本；README 明确写出该项目为 'Couchbase community-maintained'，非官方支持产品，仅通过 GitHub issue 渠道做尽力而为的维护，缺少正式的 SLA 或安全响应流程说明；同时提供了 CONTRIBUTING.md、pre-commit hook、lint 脚本等工程化治理迹象，显示有一定的工程规范。综合活跃迹象与治理/支持声明上的欠缺，给13分。
文档质量 18/20: README 内容非常详尽：涵盖 PyPI/Docker/源码三种安装方式、多个主流客户端（Claude Desktop、Cursor、Windsurf、VS Code、JetBrains）的具体配置示例、完整的环境变量/命令行参数对照表、只读模式的语义与限制说明、工具禁用与二次确认机制及其安全提示、详细的日志与日志轮转配置、OAuth 2.1 鉴权配置示例、故障排查（Troubleshooting Tips）章节、以及集成测试运行方法。文档分层清晰、示例充分、限制条件（如工具禁用不能替代RBAC）也被明确披露，达到较高水准，给18分。
安装易用性 14/20: 提供了从 uvx 一行命令安装到多客户端 JSON 配置示例的清晰路径，Docker 方式也有完整命令与网络配置说明，步骤数较少且有故障排查指引。但由于是纯静态评审，没有可验证的执行证据证明这些安装步骤在实际环境中确实可用（评分规则要求非经过验证不超过15分），同时该服务依赖用户已拥有可访问的 Couchbase 集群、证书路径等外部前置条件，存在一定环境依赖复杂度，故给14分。

静态评测 · 未实际运行收录于 2026-09-07

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络连接数据库

适合谁

需要在 AI 客户端（Claude Desktop、Cursor、Windsurf、VS Code、JetBrains IDE 等）中安全访问 Couchbase 数据的开发者与数据团队
已在使用 Couchbase（Capella 或自管理）并希望引入 LLM 辅助查询与分析的团队

不适合谁

需要完全无人值守写入生产数据库且未评估风险的场景（默认只读模式会阻止写入）
不使用 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 隐私政策

安装接入

准备工作

运行环境：Python 3.10+ · Docker

CB_CONNECTION_STRING 必填 Couchbase 集群连接字符串（如 couchbases://...），来自 Capella 控制台或自管集群配置。

CB_PASSWORD 可选密钥数据库密码，用于基本认证，属于敏感信息。

其他可选配置项（31 个）

CB_USERNAME 可选数据库用户名，用于基本认证，在 Capella 或 Couchbase Server 的 RBAC 中创建。

CB_CA_CERT_PATH 可选服务器 CA 证书路径，用于自签名/不受信证书的 TLS 验证；连 Capella 时不需要。

CB_CLIENT_CERT_PATH 可选 mTLS 客户端证书文件路径。

CB_CLIENT_KEY_PATH 可选 mTLS 客户端私钥文件路径。

CB_MCP_READ_ONLY_MODE 可选只读模式开关，默认 true，禁用所有写操作（KV、查询、scope/collection 与索引管理）。

CB_MCP_TRANSPORT 可选传输模式：stdio、http 或 sse，默认 stdio。

CB_MCP_HOST 可选 HTTP/SSE 模式下服务器监听的主机，默认 127.0.0.1。

CB_MCP_PORT 可选 HTTP/SSE 模式下服务器监听的端口，默认 8000。

CB_MCP_DISABLED_TOOLS 可选要禁用的工具，逗号分隔或指向每行一个工具名的文件路径。

CB_MCP_CONFIRMATION_REQUIRED_TOOLS 可选执行前需要用户确认（elicitation）的工具列表。

CB_MCP_LOG_LEVEL 可选日志级别：off、debug、info、warning、error，默认 info。

CB_MCP_LOG_SINKS 可选日志输出目标：stderr、file 或两者，默认 stderr。

CB_MCP_LOG_FILE 可选按级别写日志文件的基础路径，默认 mcp_server.log。

CB_MCP_LOG_ROTATION_MAX_SIZE_MB 可选每个级别日志文件轮转的最大大小（MB），默认 1。

CB_MCP_LOG_MAX_BYTES 可选已弃用的按字节轮转大小，优先级低于 CB_MCP_LOG_ROTATION_MAX_SIZE_MB。

CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB 可选覆盖 ERROR 日志文件的轮转大小（MB）。

CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB 可选覆盖 WARNING 日志文件的轮转大小（MB）。

CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB 可选覆盖 INFO 日志文件的轮转大小（MB）。

CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB 可选覆盖 DEBUG 日志文件的轮转大小（MB）。

CB_MCP_LOG_RETENTION_BACKUP_COUNT 可选每个级别保留的轮转备份文件数，默认 1。

CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT 可选覆盖 ERROR 日志保留的备份数。

CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT 可选覆盖 WARNING 日志保留的备份数。

CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT 可选覆盖 INFO 日志保留的备份数。

CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT 可选覆盖 DEBUG 日志保留的备份数。

CB_MCP_OAUTH_JWT_JWKS_URI 可选身份提供方的 JWKS 端点，用于验证 JWT 签名；启用 OAuth 必需，仅 http 传输生效。

CB_MCP_OAUTH_JWT_ISSUER 可选预期的 JWT iss 声明值；启用 OAuth 必需。

CB_MCP_OAUTH_JWT_AUDIENCE 可选预期的 JWT aud 声明值；启用 OAuth 必需。

CB_MCP_OAUTH_JWT_ALGORITHM 可选 JWT 签名算法（RS256/384/512、ES256/384/512、PS256/384/512），默认 RS256。

CB_MCP_OAUTH_MCP_BASE_URL 可选本服务器的公开基础 URL，设置后发布 RFC 9728 受保护资源元数据。

CB_MCP_OAUTH_SCOPE_READ_LABEL 可选自定义“读”权限的 OAuth scope 标签，默认 couchbase-mcp:read。

CB_MCP_OAUTH_SCOPE_WRITE_LABEL 可选自定义“写”权限的 OAuth scope 标签，默认 couchbase-mcp:write。

前置条件：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"}}}}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "couchbase": {
      "command": "uvx",
      "args": [
        "couchbase-mcp-server"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add couchbase -e CB_CONNECTION_STRING=couchbases://connection-string -e CB_USERNAME=username -e CB_PASSWORD=password -- uvx couchbase-mcp-server

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在客户端的工具列表中确认出现 couchbase 服务器的工具（如 get_buckets_in_cluster），然后让 AI 调用 test_cluster_connection 或直接询问“列出集群中的 bucket”，若能返回真实 bucket 列表即说明连接成功。

常见排障

确认从源码运行时配置中的仓库路径正确（注意末尾斜杠）
核对连接字符串、用户名、密码或证书路径是否正确
若使用 Capella，确保集群对运行 MCP 服务器的机器 IP 可访问（允许列表）
确认数据库用户至少对一个存储桶有权限
确认 uv 已正确安装且可访问，必要时在配置中提供 uv/uvx 的绝对路径
查看 MCP 客户端日志排查错误；从源码更新后可运行 uv sync 同步依赖
通过 uvx couchbase-mcp-server --version 查看服务器版本

试试这样问

连接成功后，可以直接对 AI 助手这样说：

列出集群中所有的 bucket，以及每个 bucket 下的 scope 和 collection。
查看 users collection 的 schema 结构。
查询最耗时的 5 条 SQL++ 查询，并给出索引优化建议。
根据 ID 从 travel-sample 的 airline collection 中读取一条文档。

工具能力 33

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 只读

获取集合的结构/模式

展开其余 25 个工具

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 只读

获取选择性不足的查询（索引扫描返回的文档远多于最终结果）

使用场景

用自然语言查询 Couchbase 数据并执行文档 CRUD 操作

探索集群结构与数据模式（桶、作用域、集合、Schema）

分析查询性能瓶颈并获取索引建议

创建和管理 GSI 二级索引

支持客户端

Claude Desktop

Cursor

Windsurf Editor

VS Code

JetBrains IDEs

依据项目文档列出，未经本站实测。

详细介绍

Couchbase 官方维护的自托管 MCP 服务器，允许 AI 代理连接 Capella 或自管理的 Couchbase 集群并操作其中的数据。提供集群健康、数据模式、键值（KV）、查询与性能分析五大类工具，默认启用只读模式，并支持细粒度工具禁用、执行前确认（需客户端支持 elicitation）、OAuth 2.1 授权（HTTP 传输）与详细的日志配置。通过 PyPI 包（couchbase-mcp-server）、Docker 镜像或源码运行，支持 STDIO 与 Streamable HTTP（及已弃用的 SSE）传输。