Couchbase
官方使用自然语言与存储在Couchbase集群中的数据进行交互。
你可以用 Couchbase MCP 做什么?
- 探索集群数据 — 列出存储桶、作用域和集合,然后推断
orders等集合的架构。 - 运行 SQL++ 查询 — 对存储桶和作用域执行只读 SQL++ 查询,并说明查询计划。
- 检查文档 — 按 ID 获取文档,或读取特定子文档路径,而无需加载整个文档。
- 检查集群健康状况 — 报告集群健康状况、正在运行的服务和连接诊断信息。
- 分析查询性能 — 查找运行时间最长、最频繁或未使用覆盖索引的查询。
- 搜索和向量查询 — 针对已配置的索引运行全文搜索和向量相似度查询。
文档
Couchbase MCP Server
Couchbase MCP Server 是一个自托管的 MCP Server,可让 AI 代理连接并与 Couchbase Servers(无论托管在 Capella 上还是自行管理)或 Operational Insights Enterprise 中的数据交互。它提供多种类别的工具,包括集群运行状况、数据架构、查询等,并通过只读模式和精细的工具禁用功能提供安全控制。它支持 STDIO 和 Streamable HTTP 传输,并具备 OAuth 功能。
Couchbase MCP Server 以 Python Package Index (PyPI) 软件包的形式分发,也可通过 Docker 获取。通过许可 Couchbase AI Data Plane,即可获得 Couchbase MCP Server 的企业支持,同时也有权使用 Couchbase Agent Memory 和 Couchbase Agent Catalog 并获得其企业支持。
完整文档:docs.couchbase.com/mcp-server
目录
- 为什么选择 Couchbase MCP Server
- 选择服务器
- Operational Server
- Operational Insights Server
- 通用配置
- 客户端设置
- Docker
- 故障排除
- 常见问题
- 贡献
- 使用数据、LLM 风险和支持政策
为什么选择 Couchbase MCP Server
- 默认安全 — 默认情况下不会加载写入工具,并且会阻止修改数据的查询,除非设置
CB_MCP_READ_ONLY_MODE=false;也可以禁用单个工具,或要求用户确认后才能使用。 - Couchbase Server 和 Operational Insights — operational server 使用相同的配置连接到 Couchbase Capella 或自托管的 Couchbase Server 集群;Operational Insights server 连接到自托管的 Operational Insights 集群。
- 感知 RBAC — 工具控制可引导 LLM;Couchbase 用户的基于角色的访问控制仍是权威安全边界。
- 面向生产环境的传输方式 — 本地桌面客户端可使用 STDIO;共享部署可使用支持可选 OAuth 2.1 的 Streamable HTTP(任何发布 JWKS 的 IdP:Auth0、Okta、Keycloak、Entra、Cognito 等),并支持运行状况检查和审计日志记录。Operational Server 还可以运行多个工作进程,以利用更多 CPU 核心。
- 支持任何 MCP 客户端 — 已通过 Claude Desktop、Cursor、Windsurf、VS Code 和 JetBrains AI Assistant/Junie 测试。
连接后,你可以提出如下问题:
- “我有哪些存储桶、范围和集合?
orders集合的架构是什么?” - “查找
users中满足status = 'active'的最近 10 个文档。” - “过去一小时内最慢的 5 个查询是什么?其中是否有查询缺少覆盖索引?”
- “此集群运行状况如何?正在运行哪些服务?”
- “在
products中插入一个包含以下字段的新文档:…”(需要CB_MCP_READ_ONLY_MODE=false)
选择服务器
此软件包包含两个 MCP 服务器。每个服务器都通过各自的子命令启动,连接到不同类型的集群,并提供各自的工具。选择与集群匹配的服务器,按照对应章节完成设置并了解其工具,然后参阅通用配置了解两者共用的设置。若要同时使用两者,请在 MCP 客户端中将它们分别注册为独立服务器。
| Operational server | Operational Insights server | |
|---|---|---|
| 适用对象 | Couchbase 集群(Capella 或自托管) | 自托管的 Operational Insights 集群(Capella 上不可用) |
| 子命令 | operational(默认) | operational-insights |
| 连接字符串 | couchbase:// / couchbases:// | HTTP(S) URL,例如 http://localhost:8095 |
| 凭据变量 | CB_CONNECTION_STRING、CB_USERNAME、… | CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING、CB_OPERATIONAL_INSIGHTS_USERNAME、… |
| 工具 | 52 个 — 集群运行状况、架构、KV、SQL++、索引、全文和向量搜索、查询性能 | 13 个 — 架构、SQL++(同步和异步)、索引、导出 |
| 默认 HTTP 端口 | 8000 | 8001 |
| 默认日志文件 | mcp_server.log | mcp_server_operational_insights.log |
目前,Operational Server 的子命令是可选的——直接运行
couchbase-mcp-server即可启动,但明确指定子命令可让配置更加清晰。选项应放在子命令之后:couchbase-mcp-server operational --transport=http。使用uvx couchbase-mcp-server --version检查已安装的版本。
Operational Server
operational server 使用 couchbase Python SDK 连接到 Capella 上或自托管的 Couchbase Server 集群。
Operational 快速入门
你需要一个正在运行的 Couchbase 集群——Capella 免费套餐是最快的获取方式(你可以导入示例数据集)——以及一个 MCP 客户端。将以下配置之一添加到客户端(各客户端配置文件的位置请参阅客户端设置)。如果客户端已配置其他服务器,请将 couchbase 添加到现有的 mcpServers 对象中。
通过 PyPI 使用 uvx(需要 uv 和 Python 3.11+):
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
使用 Docker(只需要 Docker):
{
"mcpServers": {
"couchbase": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_CONNECTION_STRING=couchbases://connection-string",
"-e", "CB_USERNAME=username",
"-e", "CB_PASSWORD=password",
"couchbase/mcp-server:latest", "operational"
]
}
}
}
从源代码
git clone https://github.com/couchbase/mcp-server-couchbase.git
{
"mcpServers": {
"couchbase": {
"command": "uv",
"args": [
"--directory", "path/to/cloned/repo/mcp-server-couchbase/",
"run", "src/mcp_server.py", "operational"
],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
path/to/cloned/repo/mcp-server-couchbase/ 是你克隆仓库所在的路径——请保留末尾的斜杠。拉取更新后,运行 uv sync 更新依赖项。
Operational 连接和身份验证
使用用户名和密码或客户端证书(mTLS)进行身份验证。如果两者都已设置,则使用证书。
| 环境变量 | CLI 参数 | 说明 |
|---|---|---|
CB_CONNECTION_STRING | --connection-string | 集群连接字符串。必需 |
CB_USERNAME / CB_PASSWORD | --username / --password | 基本身份验证 |
CB_CLIENT_CERT_PATH / CB_CLIENT_KEY_PATH | --client-cert-path / --client-key-path | mTLS 身份验证 |
CB_CA_CERT_PATH | --ca-cert-path | 用于自签名/不受信任服务器证书的根证书(Capella 不需要) |
mTLS 示例
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
"CB_CLIENT_KEY_PATH": "/path/to/client.key"
}
}
}
}
Operational 工具
默认情况下,只读模式开启时不会加载写入工具(标记为 ✏️)。标记为 🖥️ 的工具仅适用于自托管环境——它们使用 Capella 未公开的管理 REST 端点,或者(discover_tool_input_values)仅为相关工具提供参考数据——因此需要 self-managed Couchbase Server 7.6+,并且不会在 Capella 连接上注册。
集群设置和运行状况
| 工具 | 说明 |
|---|---|
get_server_configuration_status | 无需连接集群即可查看服务器状态和配置:只读模式、已禁用/需要确认的工具、OAuth、日志记录和审计计数器 |
test_cluster_connection | 通过连接集群检查集群凭据 |
get_cluster_health_and_services | 检查集群运行状况和正在运行的服务,可通过 service_types 进行筛选 |
get_client_connectivity_report | SDK 缓存的连接诊断信息,不进行主动网络探测 |
get_cluster_metrics 🖥️ | 指定历史时间范围内的集群统计信息(stats-range 端点) |
get_cluster_tasks 🖥️ | 当前正在运行的任务——重新平衡、压缩、XDCR、索引构建。需要 ro_admin |
get_cluster_health_snapshot 🖥️ | 每个节点的运行状况:服务拓扑、成员状态、协调器和运行状况汇总。需要 ro_admin |
get_bucket_config 🖥️ | 一个或所有存储桶的配置和实时状态——配额、淘汰策略、副本、持久性、存储、压缩。需要 ro_admin |
get_cluster_system_events 🖥️ | 系统事件日志(配置更改、故障转移、重新平衡、重启),可通过 since_time 指定时间范围。需要 Full Admin 或 Cluster Admin |
discover_tool_input_values 🖥️ | 查找其他工具所需的确切输入值(例如 get_cluster_metrics 的所有指标名称)。可离线使用 |
数据模型和架构发现
| 工具 | 说明 |
|---|---|
get_buckets_in_cluster | 列出集群中的所有存储桶 |
get_scopes_in_bucket | 列出存储桶中的所有范围 |
get_collections_in_scope | 列出范围中的所有集合(需要 Query 服务) |
get_scopes_and_collections_in_bucket | 列出存储桶中的所有范围和集合 |
get_schema_for_collection | 推断集合的结构 |
create_scope ✏️ | 在存储桶中创建范围(Server 7.6+ 和 Capella) |
create_collection ✏️ | 在现有范围中创建集合(Server 7.6+ 和 Capella) |
delete_scope ✏️ | 删除范围及其所有集合——永久操作 |
delete_collection ✏️ | 删除集合及其所有文档——永久操作 |
文档(KV)操作
| 工具 | 说明 |
|---|---|
get_document_by_id | 按 ID 获取文档 |
lookup_subdocument | 读取指定路径、检查是否存在或统计数量,而无需获取整个文档 |
upsert_document_by_id ✏️ | 按 ID 插入或更新文档 |
insert_document_by_id ✏️ | 插入新文档(如果文档已存在则失败) |
replace_document_by_id ✏️ | 替换现有文档(如果文档不存在则失败) |
delete_document_by_id ✏️ | 按 ID 删除文档 |
mutate_subdocument ✏️ | 修改现有文档中的路径(插入或更新、插入、替换、移除、数组操作、计数器) |
查询和索引
| 工具 | 说明 |
|---|---|
run_sql_plus_plus_query | 运行限定在存储桶和范围内的 SQL++ 查询——直接使用集合名称(SELECT * FROM users)。只读模式下会阻止修改数据的语句 |
explain_sql_plus_plus_query | 生成并评估 EXPLAIN 计划:元数据、提取的计划和分析结果 |
get_index_advisor_recommendations | 为 SQL++ 查询提供索引顾问建议 |
list_indexes | 列出索引及其定义,可按存储桶/范围/集合/名称筛选;标记向量索引(is_vector、vector_type) |
get_index_stats 🖥️ | 按节点查看每个索引的大小、碎片、扫描流量和延迟——用于发现资源压力和未使用的索引 |
create_query_index ✏️ | 创建标量、Hyperscale 向量或 Composite 向量 GSI 索引(index_type)。默认延迟构建——随后运行 build_index |
create_index ✏️ | 已弃用——请使用 create_query_index。已在 2.0 中移除 |
build_index ✏️ | 构建集合中所有延迟构建的索引 |
drop_index ✏️ | 删除 GSI 索引(标量或向量) |
全文搜索(FTS)
需要 Couchbase Server 7.6+ 和 Search 服务。支持范围级和集群级(旧版)索引:范围级索引需同时传入 bucket_name 和 scope_name;否则两者都省略。
| 工具 | 描述 |
|---|---|
list_search_indexes | 列出 Search 索引 — 集群级别、按存储桶或按作用域 |
get_search_index_definition | 单个 Search 索引的完整定义(映射、分析器、计划参数) |
run_search | 根据原始 JSON 正文运行任意非向量 FTS 查询;explain=true 返回执行计划 |
upsert_search_index ✏️ | 创建或更新 Search 索引,包括向量字段映射。更新会触发完整重建 — 传入当前的 uuid,以避免覆盖并发更改 |
drop_search_index ✏️ | 删除 Search 索引 — 永久删除 |
向量搜索
这两个工具都会使用 Embedding Providers 中配置的模型来嵌入纯文本查询。适用于自管理的 Couchbase Server 和 Capella。
| 工具 | 描述 |
|---|---|
run_vector_query | 通过 APPROX_VECTOR_DISTANCE() 对 GSI 向量索引执行相似度搜索(Server 8.0+)。自动选择索引;支持 SQL++ where 预过滤和 Hyperscale 调优(num_probes、rerank、top_n_scan)。返回完整文档 |
run_vector_search | 对命名索引执行 Search 服务向量搜索(Server 7.6+)。scalar_query 可启用混合搜索;prefilter 可先缩小候选范围。每个命中项返回索引中存储的字段 |
查询性能分析
| 工具 | 描述 |
|---|---|
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 | 扫描(辅助索引、主索引或顺序扫描)返回的文档远多于最终结果的查询 |
查询服务运行状况 🖥️
这些工具会在每次查询时调用每个查询节点上 Query 服务自身的管理 REST API。
| 工具 | 描述 |
|---|---|
get_cluster_query_vitals | 查询引擎运行状况:请求速率、活动/排队请求、内存、GC、运行时间。需要 ro_admin |
get_active_queries | 当前在所有查询节点上执行的查询。需要 ro_admin |
delete_active_query ✏️ | 根据请求 ID 取消正在执行的查询。需要 Full Admin 或 Cluster Admin |
在 Capella 上自动禁用的工具
🖥️ 工具通过管理 REST 端点访问 Couchbase,而 Capella 不会公开这些端点(唯一例外是 discover_tool_input_values,由于它只为需要这些端点的工具提供服务,因此也会被禁用)。当 CB_CONNECTION_STRING 中的所有主机都以 .cloud.couchbase.com 结尾时,服务器不会注册这些工具,并会在 get_server_configuration_status 和启动日志中将它们与您自己的已禁用工具一并报告。基于 SDK 的工具(例如 get_cluster_health_and_services 和 get_client_connectivity_report)仍可使用。
| 工具 | 所需端点 |
|---|---|
get_cluster_metrics | Management REST(/pools/default/stats/range) |
get_cluster_tasks | Management REST(/pools/default/tasks) |
get_bucket_config | Management REST(/pools/default/buckets[/<name>]) |
get_cluster_health_snapshot | Management REST,以及每个节点的端点 |
get_cluster_system_events | Management REST(/events) |
get_index_stats | Index Service REST(每个索引器的 /api/v1/stats) |
get_cluster_query_vitals | Query service REST(/admin/vitals) |
get_active_queries | Query service REST(/admin/active_requests) |
delete_active_query | Query service REST(DELETE /admin/active_requests/{id}) |
discover_tool_input_values | 无(可离线运行),但它只为 get_cluster_metrics 提供服务,而 Capella 不具备该工具 |
嵌入提供程序
run_vector_query 和 run_vector_search 使用 CB_MCP_EMBEDDING_MODEL_PROVIDER 中设置的提供程序来嵌入查询文本。此项为可选:未设置时,服务器仍会正常启动,且这两个工具仍会注册,但调用时会返回错误,说明需要设置什么。
CB_MCP_EMBEDDING_MODEL_PROVIDER | 必需 | 可选 | 备注 |
|---|---|---|---|
capella | CB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODEL、CB_MCP_EMBEDDING_MODEL_ENDPOINT | — | Capella Model Service。CB_MCP_EMBEDDING_MODEL_ENDPOINT 是您部署专属的 URL(例如 https://<id>.ai.couchbase.com),可在 Capella 的 AI Data Plane > Models 中找到 |
openai | CB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | 设置端点以使用兼容 OpenAI 的本地服务器(Ollama、vLLM、LM Studio) |
cohere | CB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
voyage | CB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_ENDPOINT | |
bedrock | CB_MCP_EMBEDDING_MODEL | CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID、CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY、CB_MCP_EMBEDDING_MODEL_AWS_REGION | Amazon Titan 嵌入模型(例如 amazon.titan-embed-text-v2:0)— 提供程序会发送 Titan 的 inputText 请求格式,因此目前尚不支持 Cohere Embed 等其他 Bedrock 嵌入模型。省略凭据即可使用默认 AWS 凭据链。需要额外的:pip install couchbase-mcp-server[bedrock-embeddings] |
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password",
"CB_MCP_EMBEDDING_MODEL_PROVIDER": "openai",
"CB_MCP_EMBEDDING_MODEL": "text-embedding-3-small",
"CB_MCP_EMBEDDING_MODEL_API_KEY": "sk-..."
}
所有选项
适用于 operational server
的所有环境变量和 CLI 标志
Operational Insights server 接受相同的选项,但它有自己的连接设置,且没有 CB_MCP_EMBEDDING_MODEL_* 选项。
| 环境变量 | CLI 参数 | 描述 | 默认值 |
|---|---|---|---|
CB_CONNECTION_STRING | --connection-string | Couchbase 集群的连接字符串 | 必填 |
CB_USERNAME | --username | 可访问所需存储桶、用于基本身份验证的用户名 | 必填(或需要客户端证书和密钥以使用 mTLS) |
CB_PASSWORD | --password | 用于基本身份验证的密码 | 必填(或需要客户端证书和密钥以使用 mTLS) |
CB_CLIENT_CERT_PATH | --client-cert-path | 用于 mTLS 身份验证的客户端证书文件路径 | 使用 mTLS 时必填(或需要用户名和密码) |
CB_CLIENT_KEY_PATH | --client-key-path | 用于 mTLS 身份验证的客户端密钥文件路径 | 使用 mTLS 时必填(或需要用户名和密码) |
CB_CA_CERT_PATH | --ca-cert-path | 当服务器配置了自签名/不受信任证书时,用于 TLS 的服务器根证书路径。连接到 Capella 时无需此项 | |
CB_MCP_READ_ONLY_MODE | --read-only-mode | 禁止所有数据修改(KV、Query、范围/集合管理、索引管理和 FTS 索引管理)。启用后,不会加载写入工具。 | true |
CB_MCP_TRANSPORT | --transport | 传输模式:stdio、http | stdio |
CB_MCP_HOST | --host | HTTP 传输模式的主机 | 127.0.0.1 |
CB_MCP_PORT | --port | HTTP 传输模式的端口 | 8000 |
CB_MCP_WORKERS | --workers | http 传输模式的服务器工作进程数。值大于 1 时将以无状态 HTTP 模式运行(参见多个工作进程) | 1 |
CB_MCP_STATELESS_HTTP | --stateless-http | 处理每个 HTTP 请求时不保留会话状态。仅在使用 http 时生效;不能与需要确认的工具同时使用(参见多个工作进程) | 工作进程数 > 1 时为 true,否则为 false |
CB_MCP_DISABLED_TOOLS | --disabled-tools | 要禁用的工具(参见禁用工具) | 无 |
CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | 通过 MCP elicitation 在执行前需要用户明确确认的工具(参见要求确认) | 无 |
CB_MCP_LOG_LEVEL | --log-level | MCP 服务器的日志级别:off、debug、info、warning、error(参见日志记录) | info |
CB_MCP_LOG_SINKS | --log-sinks | 以逗号分隔的日志目标:stderr、file,或两者兼用(参见日志记录) | stderr |
CB_MCP_LOG_FILE | --log-file | 各级别日志文件的基础路径(仅在启用 file 接收器时使用) | mcp_server.log |
CB_MCP_LOG_ROTATION_MAX_SIZE_MB | --log-rotation-max-size-mb | 每个日志文件轮转前的全局最大大小,单位为 MB;除非另行指定,否则适用于所有级别。0 — 或无法使用的值,例如负数、nan 或 inf — 均无效,将回退到默认值并在启动时发出警告 | 1(1 MB) |
CB_MCP_LOG_MAX_BYTES | --log-max-bytes | 已弃用 — 请使用 CB_MCP_LOG_ROTATION_MAX_SIZE_MB(MB)。全局轮转大小,单位为字节,为保持向后兼容仍会生效;如果同时设置了 CB_MCP_LOG_ROTATION_MAX_SIZE_MB,则忽略此项 | 未设置 |
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB | --log-error-rotation-max-size-mb | ERROR 日志文件的轮转大小,单位为 MB;覆盖 ERROR 的 CB_MCP_LOG_ROTATION_MAX_SIZE_MB | 继承 CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB | --log-warning-rotation-max-size-mb | WARNING 日志文件的轮转大小,单位为 MB;覆盖 WARNING 的 CB_MCP_LOG_ROTATION_MAX_SIZE_MB | 继承 CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB | --log-info-rotation-max-size-mb | INFO 日志文件的轮转大小,单位为 MB;覆盖 INFO 的 CB_MCP_LOG_ROTATION_MAX_SIZE_MB | 继承 CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB | --log-debug-rotation-max-size-mb | DEBUG 日志文件的轮转大小,单位为 MB;覆盖 DEBUG 的 CB_MCP_LOG_ROTATION_MAX_SIZE_MB | 继承 CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_RETENTION_BACKUP_COUNT | --log-retention-backup-count | 每个级别的日志文件保留的轮转备份文件数(不包括当前文件);除非另行指定,否则适用于所有级别。0 表示仅保留当前文件(参见日志记录) | 1 |
CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT | --log-error-retention-backup-count | ERROR 日志文件保留的轮转备份数;覆盖 ERROR 的全局数量 | 继承 CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT | --log-warning-retention-backup-count | WARNING 日志文件保留的轮转备份数;覆盖 WARNING 的全局数量 | 继承 CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT | --log-info-retention-backup-count | INFO 日志文件保留的轮转备份数;覆盖 INFO 的全局数量 | 继承 CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT | --log-debug-retention-backup-count | DEBUG 日志文件保留的轮转备份数;覆盖 DEBUG 的全局数量 | 继承 CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_OAUTH_JWT_JWKS_URI | --oauth-jwks-uri | 用于验证 bearer JWT 的身份提供方 JWKS 端点。与颁发者和受众一起设置时启用 OAuth(参见OAuth 2.1 授权) | 无 |
CB_MCP_OAUTH_JWT_ISSUER | --oauth-issuer | 预期的 JWT iss 声明。启用 OAuth 时必填 | 无 |
CB_MCP_OAUTH_JWT_AUDIENCE | --oauth-audience | 预期的 JWT aud 声明。启用 OAuth 时必填 | 无 |
CB_MCP_OAUTH_JWT_ALGORITHM | --oauth-algorithm | JWT 签名算法:可选值为 RS256/384/512、ES256/384/512、PS256/384/512 | RS256 |
CB_MCP_OAUTH_MCP_BASE_URL | --oauth-mcp-base-url | 此服务器的公共基础 URL。设置后,将发布 RFC 9728 受保护资源元数据,供支持 PRM 的客户端发现身份提供方 | 无 |
CB_MCP_OAUTH_SCOPE_READ_LABEL | --oauth-scope-read-label | 覆盖被视为“读取”访问权限的 OAuth 范围标签(在 PRM 中公布,并与令牌的 scope/scp 声明匹配)。当身份提供方无法发出规范形式时使用 | couchbase-mcp:read |
CB_MCP_OAUTH_SCOPE_WRITE_LABEL | --oauth-scope-write-label | 覆盖被视为“写入”访问权限的 OAuth 范围标签;语义与读取标签相同 | couchbase-mcp:write |
CB_MCP_AUDIT_LOG_ENABLED | --audit-log-enabled | 启用审计日志记录 — 与 CB_MCP_LOG_* 操作日志使用不同的接收器,具有稳定的架构和独立的保留策略(参见审计) | false |
CB_MCP_AUDIT_LOG_SINKS | --audit-log-sinks | 以逗号分隔的审计目标:console、file,或两者兼用。console 写入 stderr — 绝不写入 stdout,因为 stdio 上的 JSON-RPC 协议使用 stdout | console |
CB_MCP_AUDIT_LOG_FILE_PATH | --audit-log-file-path | 审计日志文件路径。当接收器中包含 file 时必填;主机名和进程 ID 会插入扩展名前(audit.log → audit.<host>.<pid>.log) | 无 |
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB | --audit-log-rotation-max-size-mb | 当前审计文件轮转前可达到的最大大小,单位为 MB。0 会关闭基于大小的轮转 | 10(10 MB) |
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL | --audit-log-rotation-interval | 当前审计文件轮转前可达到的最长时间,格式为 <value><unit>,其中单位为 d(24 小时)或 w(7 天)— 例如 1d、30d、8w。0 会关闭基于时间间隔的轮转 | 1d |
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS | --audit-log-retention-max-backups | 每个审计文件保留的轮转备份数,不包括当前文件。备份文件会进行 gzip 压缩。0 表示不保留备份。此项限制的是单个文件,而非目录 — 参见审计 | 10 |
CB_MCP_AUDIT_LOG_TOOL_ARGS | --audit-log-tool-args | 在审计日志中记录工具参数值。默认关闭 — 此版本不提供脱敏功能,因此启用后会原样写入参数,包括完整的文档正文 | false |
CB_MCP_AUDIT_LOG_DISABLED_EVENTS | --audit-log-disabled-events | 要抑制的审计事件:以逗号分隔的数字事件 ID(例如 61490,61492),或每行一个 ID 的文件。只能抑制可筛选的事件 | 无 |
CB_MCP_EMBEDDING_MODEL_PROVIDER | --embedding-model-provider | run_vector_query / run_vector_search 的嵌入提供方:可选值为 capella、openai、cohere、voyage、bedrock。未设置时,两个工具的嵌入步骤都会停用,直到完成配置 — 参见嵌入提供方配置 | 无 |
CB_MCP_EMBEDDING_MODEL | --embedding-model | 已配置嵌入提供方的模型名称/ID | 无 |
CB_MCP_EMBEDDING_MODEL_API_KEY | --embedding-model-api-key | 已配置提供方的 API 密钥。bedrock 不使用此项(而是使用 AWS 凭证链 / CB_MCP_EMBEDDING_MODEL_AWS_*) | 无 |
CB_MCP_EMBEDDING_MODEL_ENDPOINT | --embedding-model-endpoint | 基础 URL 覆盖值(兼容 OpenAI 的本地服务器,或 Capella Model Service 部署自身的 URL — 使用 CB_MCP_EMBEDDING_MODEL_PROVIDER=capella 时必填) | 无 |
CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID | --embedding-model-aws-access-key-id | AWS 访问密钥 ID,仅适用于 bedrock 提供方。省略时使用默认 AWS 凭证链 | 无 |
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY | --embedding-model-aws-secret-access-key | AWS 秘密访问密钥,仅适用于 bedrock 提供方 | 无 |
CB_MCP_EMBEDDING_MODEL_AWS_REGION | --embedding-model-aws-region | AWS 区域,仅适用于 bedrock 提供方。未设置时,回退到 AWS SDK 自身的区域解析机制 | 无 |
Operational Insights 服务器
operational-insights 服务器连接到自管理的 Operational Insights 集群。Operational Insights 是面向实时应用和运营智能的实时分析数据库(RT-OLAP)。此服务器不适用于 Capella。它使用 couchbase-operational-insights SDK。该服务器作为独立进程运行,与操作服务器分开。
[!IMPORTANT]
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING是一个 HTTP(S) URL,而不是couchbase://连接字符串 — 例如http://localhost:8095,或通过 TLS 使用https://<host>:18095。这是最常见的配置错误。
Operational Insights 快速入门
通过 uvx 从 PyPI 安装:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational-insights"],
"env": {
"CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "http://localhost:8095",
"CB_OPERATIONAL_INSIGHTS_USERNAME": "Administrator",
"CB_OPERATIONAL_INSIGHTS_PASSWORD": "password"
}
}
}
}
使用 Docker:
{
"mcpServers": {
"couchbase-operational-insights": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=http://host.docker.internal:8095",
"-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=Administrator",
"-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=password",
"couchbase/mcp-server:latest", "operational-insights"
]
}
}
}
从源代码运行时,请使用操作服务器源代码配置,并将 operational-insights 作为最后一个参数,同时提供上述变量。
Operational Insights 连接和身份验证
| 环境变量 | CLI 参数 | 描述 |
|---|---|---|
CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING | --connection-string | 端点 URL(HTTP/HTTPS)。必需 |
CB_OPERATIONAL_INSIGHTS_USERNAME | --username | 用户名 |
CB_OPERATIONAL_INSIGHTS_PASSWORD | --password | 密码 |
CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH | --ca-cert-path | 用于自签名/不受信任服务器证书的根证书(PEM) |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH | --client-cert-path | 用于 mTLS 的客户端证书 — PEM(含密钥)或 PKCS#12 捆绑包(.p12/.pfx,不含密钥)。需要 https:// URL;会覆盖用户名/密码 |
CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH | --client-key-path | 客户端证书的私钥(PEM)。使用 PKCS#12 时留空 |
CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD | --client-cert-password | 加密密钥或 PKCS#12 捆绑包的密码 |
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE | --operational-insights-query-result-max-size | 查询结果大小上限,以字节为单位。未设置表示不限制。设置后,读取会在达到预算时停止,响应会报告 truncated: true;超出预算的行不会返回。超过 4 MiB(4194304)的值会被限制为 4 MiB,并在启动时向 stderr 输出警告 |
CB_MCP_OPERATIONAL_INSIGHTS_ASYNC_QUERY_RESULT_TIMEOUT | --operational-insights-async-query-result-timeout | 每个异步查询请求的超时时间,以秒为单位:启动查询、检查状态、获取结果、丢弃和取消。对于获取操作,该超时涵盖整个下载,因此读取结果所需时间超过此值时会失败。对于大型结果或较慢的连接,请调高此值。正整数,默认值为 30,最大值为 600。更大的值会被限制为 600 并输出警告;其他无效值会记录为警告,并使用 30 |
所有通用配置均适用,但与操作服务器相比有以下差异:
- 默认端口为
8001,默认日志文件为mcp_server_operational_insights.log,因此两个服务器可以并行运行。 - 仅支持一个工作进程(
CB_MCP_WORKERS=1),因为异步查询句柄存储在进程内存中。 - 它没有
CB_MCP_EMBEDDING_MODEL_*选项。
Operational Insights 工具
除 get_server_configuration_status 外,所有名称都带有前缀 operational_insights_,因此可以在同一个客户端中注册两个服务器而不会发生冲突。启用只读模式(默认)时,写入工具(标记为 ✏️)不会加载。
服务器状态
| 工具 | 描述 |
|---|---|
get_server_configuration_status | 与操作服务器上的同名工具相同 |
数据模型与架构发现
| 工具 | 描述 |
|---|---|
operational_insights_get_databases_in_cluster | 列出数据库 |
operational_insights_get_scopes_in_database | 列出数据库中的范围 |
operational_insights_get_collections_in_scope | 列出范围中的集合(数据集) |
operational_insights_get_schema_for_collection | 通过采样推断集合的 JSON 架构 |
查询与索引
| 工具 | 描述 |
|---|---|
operational_insights_list_indexes | 列出 System.Metadata.Index 中的二级索引 |
operational_insights_explain_query | 对 SQL++ 语句执行 EXPLAIN,但不运行该语句 |
operational_insights_run_query_sync | 运行 SQL++ 并返回行数不超过结果大小上限的结果;也可以改为导出。服务器端会强制执行只读模式 |
operational_insights_run_query_async | 启动长时间运行的查询,并立即返回 query_handle,不等待行结果;大型导出也优先使用此工具。服务器端会强制执行只读模式 |
operational_insights_get_async_query_results | 轮询异步查询;就绪后返回行(或导出目标位置) |
operational_insights_discard_async_query_results | 释放已完成异步查询的结果 |
operational_insights_cancel_async_query | 停止仍在运行的异步查询(只读模式下允许) |
operational_insights_create_index ✏️ | 通过 CREATE INDEX 创建二级索引 |
异步查询遵循启动 → 轮询 → 丢弃或取消的流程:operational_insights_run_query_async 返回一个 query_handle,轮询 operational_insights_get_async_query_results 直到查询就绪,然后由 operational_insights_discard_async_query_results 释放结果,或者由 operational_insights_cancel_async_query 停止仍在运行的查询。
导出大型结果
operational_insights_run_query_sync 和 operational_insights_run_query_async 可以将语句包装在 COPY ... TO 中,并将行写入外部对象存储,而不是返回行。传入以下三个参数:copy_to_link(使用 CREATE LINK ... TYPE S3 创建的现有链接)、copy_to_bucket 和 copy_to_path;还可以选择传入 copy_to_format(默认值为 json,或使用 parquet)。随后,该工具会返回确认信息,不包含任何行:
{
"success": true,
"exported": true,
"destination": {"link": "s3Link", "bucket": "my-exports", "path": "exports/run1", "format": "json"},
"message": "Results were written to my-exports/exports/run1 as json. ..."
}
- 如果目标位置不完整,操作会被拒绝,而不会悄悄改为返回行。
- 同步工具会等待整个上传完成;导出大型结果时优先使用异步工具。
- 只读模式下会阻止导出(因为导出会写入外部存储),因此需要
CB_MCP_READ_ONLY_MODE=false或具有couchbase-mcp:write的令牌。 - 不提供
csv,因为它需要显式输出架构,而该架构无法从任意SELECT推断出来。
通用配置
这些设置对两个服务器的作用相同。每个选项都可以设置为环境变量,或作为子命令后的 CLI 标志。
安全控制
遵循以下安全原则:
- 为数据库用户授予最小权限 — RBAC 是权威的安全边界(见下文)。
- 仅提供代理所需的工具,并禁用其余工具 — 每个已加载的工具都可供 LLM 调用。使用只读模式和
CB_MCP_DISABLED_TOOLS,将工具列表缩减到最低限度。 - 要求对保留的敏感工具进行确认 — 请参阅要求确认。
以下控制分为三个层级,从范围最广到最窄。请结合使用,但请记住,它们都不能替代 RBAC。
[!IMPORTANT] 数据库用户的 RBAC 权限是权威的安全控制。例如,禁用
upsert_document_by_id和delete_document_by_id并不能阻止run_sql_plus_plus_query运行INSERT/UPDATE/DELETE/MERGE— 只有只读模式或缺少 RBAC 权限才能阻止。仅向服务器的数据库用户授予其所需的权限。
只读模式
CB_MCP_READ_ONLY_MODE(默认值为 true)是控制写入的唯一开关:
true— 各服务器工具列表中标记为 ✏️ 的写入工具不会加载,并且会阻止修改数据或结构的查询。false— 加载写入工具,并允许执行修改查询。
禁用工具
CB_MCP_DISABLED_TOOLS 会将工具从发现结果中完全移除。它接受逗号分隔的列表,或包含每行一个工具名称的文件路径(# 用于开始注释):
CB_MCP_DISABLED_TOOLS="upsert_document_by_id,delete_document_by_id"
# or
CB_MCP_DISABLED_TOOLS=/path/to/disabled_tools.txt
# disabled_tools.txt
# Write operations
upsert_document_by_id
delete_document_by_id
# Index advisor
get_index_advisor_recommendations
在 Capella 上,操作服务器还会自动禁用某些管理工具。
要求确认(elicitation)
CB_MCP_CONFIRMATION_REQUIRED_TOOLS 会使用 MCP elicitation,在列出的工具运行前要求用户确认。它接受与禁用工具相同的逗号分隔列表或文件格式:
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"
- 如果客户端支持 elicitation,工具运行前会提示用户确认。
- 如果客户端不支持,为保持向后兼容,工具会在未经确认的情况下运行。
- 确认需要 MCP 会话,因此不能与无状态 HTTP(
CB_MCP_STATELESS_HTTP=true或大于 1 的CB_MCP_WORKERS)结合使用。服务器会拒绝以这种组合启动。在负载均衡器后使用时,确认需要粘性会话 — 请参阅负载均衡器。
传输方式
| 传输方式 | 适用场景 | 端点 |
|---|---|---|
stdio(默认) | 一个本地客户端将服务器作为子进程启动 | — |
http | 多个客户端共享一个服务器;支持 OAuth、运行状况检查以及操作服务器上的工作进程 | http://<host>:<port>/mcp |
使用 CB_MCP_TRANSPORT 设置传输方式,使用 CB_MCP_HOST 设置绑定地址(默认值为 127.0.0.1),并使用 CB_MCP_PORT 设置端口(未设置时使用各服务器的默认端口)。如果未启用 OAuth,HTTP 端点不需要身份验证。
uvx couchbase-mcp-server operational \
--connection-string='<couchbase_connection_string>' \
--username='<database_username>' \
--password='<database_password>' \
--transport=http
然后将客户端指向该 URL:
{
"mcpServers": {
"couchbase-http": {
"url": "http://localhost:8000/mcp"
}
}
}
多个工作进程
一个进程最多使用约一个 CPU 核心。--workers N(CB_MCP_WORKERS)会在同一主机和端口后运行 N 个进程;可用核心数是一个不错的起始值。只有操作服务器支持工作进程。使用多个工作进程时:
- 必须使用
http传输方式,并且服务器会以无状态 HTTP 模式运行,因为客户端的请求可能到达不同的工作进程。也可以在单个工作进程上设置--stateless-http=true,例如在没有粘性会话的负载均衡器后运行时。 - 不能使用需要确认的工具。
- 每个进程都会写入自己的日志文件,文件名包含主机名和进程 ID(
mcp_server.<host>.<pid>.info.log)——监督进程一组,每个工作进程各一组。
负载均衡器
可以在负载均衡器后运行多个服务器实例。每个实例都将自己的 MCP 会话保存在内存中,因此负载均衡器的设置决定了哪些功能可用:
| 负载均衡器 | 服务器设置 | 需要确认的工具 |
|---|---|---|
粘性会话,按 Mcp-Session-Id 请求标头路由 | 单个工作进程,有状态(默认) | 支持 |
| 无粘性会话 | --stateless-http=true | 不支持 — 如果配置了这些工具,服务器会拒绝启动 |
- 没有粘性会话时,有状态实例会拒绝所有会话由其他实例创建的请求。此时请使用无状态模式。
- 请按
Mcp-Session-Id标头路由,而不是按 Cookie 路由。许多 MCP 客户端不会保留 Cookie。 - 如果实例重启或发生故障转移,其会话和所有待处理的确认提示都会丢失。客户端必须启动新会话。
- Operational Insights 异步查询会将其
query_handle保存在启动查询的实例内存中,即使在无状态模式下也是如此。在其他实例上轮询、丢弃或取消查询会返回Unknown query_handle。请在单个实例上使用这些工具,或使用粘性会话,确保所有调用都到达启动查询的实例。无状态模式不会发送Mcp-Session-Id,因此需要其他亲和性键,例如客户端 IP 地址。
运行状况检查
在 HTTP 模式下,GET /health 会在 MCP 端口上返回 {"status": "ok", "server": "<server>"}。这是存活检查:它不会连接到集群(因此集群中断不会导致健康容器重启),即使启用了 OAuth 也无需身份验证,并且由每个工作进程提供服务。探测示例请参阅 Docker。
OAuth 2.1 授权
启用 --transport=http 后,任一服务器都可以充当 OAuth 2.1 资源服务器,根据身份提供商的 JWKS 验证 bearer JWT。它适用于任何发布 JWKS 的 OAuth 2.1/OIDC 提供商,但不会签发令牌或管理用户。在 stdio 上会忽略 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 受保护资源元数据,以便客户端发现授权服务器。- 访问权限由令牌的
scope/scp声明中的两个作用域控制:couchbase-mcp:read(读取工具)和couchbase-mcp:write(写入工具)。完全访问需要同时具备两者。如果 IdP 无法发出这些标签,可使用CB_MCP_OAUTH_SCOPE_READ_LABEL/CB_MCP_OAUTH_SCOPE_WRITE_LABEL重命名。两个服务器使用相同的标签,因此一套 IdP 配置即可覆盖两者。
uvx couchbase-mcp-server operational \
--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>'
有关 IdP 设置,请参阅操作服务器和 Operational Insights 服务器的 OAuth 文档。
日志记录
默认情况下,每个服务器都会以 info 级别将日志写入 stderr。
CB_MCP_LOG_LEVEL—off、error、warning、info(生命周期事件和工具调用)或debug。CB_MCP_LOG_SINKS—stderr、file,或两者兼用。使用file时,每个级别会在CB_MCP_LOG_FILE旁写入一个轮换文件(mcp_server.info.log、mcp_server.error.log,……)。- 轮换和保留 —
CB_MCP_LOG_ROTATION_MAX_SIZE_MB(默认 1 MB)和CB_MCP_LOG_RETENTION_BACKUP_COUNT(默认 1)适用于所有级别;使用CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB/CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT可按级别覆盖。无效大小会回退到默认值,并在启动时发出警告。CB_MCP_LOG_MAX_BYTES已弃用。 - 配置快照 — 使用
file接收器时,每次启动都会将环境和已脱敏的服务器配置以 JSON 记录的形式写入mcp_server_config.log.json,以便提供支持。
# Debug logging to stderr and rotating per-level files
uvx couchbase-mcp-server operational --log-level=debug --log-sinks=stderr,file
MCP 客户端通常也会捕获服务器的 stderr — 位置请参阅客户端设置。详情请参阅运营服务器和 Operational Insights 服务器的日志记录文档。
审计
审计日志记录谁做了什么,以及是否获准 — 与记录出错情况的运营日志分开。对于代理,MCP 服务器是唯一能够回答这个问题的层:每个请求都以单个数据库用户的身份到达集群,而范围拒绝、只读拦截或确认被拒绝等决策根本不会到达集群。
默认关闭审计功能。使用 CB_MCP_AUDIT_LOG_ENABLED=true 启用;除非设置 CB_MCP_AUDIT_LOG_SINKS=file 和 CB_MCP_AUDIT_LOG_FILE_PATH,否则日志会写入 stderr。
# 90 days of daily, gzipped audit files
uvx couchbase-mcp-server operational --audit-log-enabled=true \
--audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
--audit-log-rotation-interval=1d --audit-log-rotation-max-size-mb=0 \
--audit-log-retention-max-backups=90
记录采用 JSON Lines 格式,字段词汇与 Couchbase Server 和 Sync Gateway 相同:
{"id":61522,"name":"document write","description":"A document write operation was requested through a tool","timestamp":"2026-09-29T09:14:22.418Z","real_userid":{"domain":"oauth","user":"agent-svc-7"},"server":{"version":"1.0.2","host":"mcp-01"},"cid":"9f2c...","outcome":"success","tool_name":"upsert_document_by_id","required_scope":"write","ks":"travel-sample.inventory.airline","cb_userid":"mcp_service"}
审计的工作方式
- 身份 —
real_userid是调用方:oauth(令牌主体)、local(stdio 模式下的 OS 用户)或anonymous(不使用 OAuth 的 HTTP 模式,启动时会发出警告)。 - 关联 —
cid将同一请求的所有记录归为一组,并作为 SQL++client_context_id发送,因此可与 Couchbase Server 的clientContextId精确关联。这里有意不设置会话标识符。 - 事件 — 固定的编号目录(生命周期、初始化、令牌被拒绝、范围被拒绝、只读拦截、确认被拒绝/跳过,以及每个工具类别对应的一对读/写事件)。
query和search是例外:每项都记录为单个事件,而不是读/写事件对,因为对于由语句驱动和搜索类接口,无法可靠地区分读写操作。向量操作归入这两个类别。完整目录以descriptor.json的形式随软件包提供。运营服务器使用区块0xF000(61440),Operational Insights 使用0x10000(65536),两者共用0xE000(57344)记录核心事件。 - 筛选 —
CB_MCP_AUDIT_LOG_DISABLED_EVENTS按数字 ID 抑制读事件(例如61490,61492)。写入和安全事件无法禁用,单事件类别query(61507,或 Operational Insights 中的 65603)和search(61510)也无法禁用:每个类别的单个事件同时涵盖其写入和读取操作,因此关闭它会丢失变更记录。 - 轮换 — 按大小(
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB,默认 10)和时间(CB_MCP_AUDIT_LOG_ROTATION_INTERVAL,默认1d)轮换,以先达到的条件为准;0可关闭任一条件。轮换后的文件会添加时间戳并进行 gzip 压缩;当前文件保持纯文本,以便tail -f使用。 - 每个进程单独生成文件 — 文件名中会加入主机名和 pid(
audit.log→audit.<host>.<pid>.log),因此并发进程不会共用同一个文件。 - 保留策略按文件计算 —
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS(默认 10)限制单个文件的备份数量。每个新进程都会写入新文件,且不会清理旧文件,因此请合理规划卷容量,或清理旧的audit.*.log*文件。 - 故障时继续运行 — 如果无法写入文件,服务器会继续提供服务并统计丢弃的记录;
get_server_configuration_status会报告written/dropped/write_errors。 - 工具参数 — 仅在使用
CB_MCP_AUDIT_LOG_TOOL_ARGS=true时记录,启动时会发出警告。此版本不会进行脱敏,因此包括完整文档正文在内的参数都会原样写入。
客户端设置
每个客户端都需要在自己的配置位置添加服务器配置,可参考运营服务器或 Operational Insights快速入门。以下示例使用运营服务器。
Claude Desktop
- 打开配置文件(参阅 MCP 快速入门指南):
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- 在
mcpServers下添加服务器,然后重启 Claude Desktop。
**日志:**macOS ~/Library/Logs/Claude,Windows %APPDATA%\Claude\Logs。参阅 MCP 故障排除指南。
Cursor
- 前往 Cursor Settings > Tools & Integrations > MCP Tools(参阅 Cursor 的 MCP 文档),或使用一键式在 Cursor 中安装链接 — 然后替换占位连接字符串和凭据。
- 在
mcpServers下添加配置并保存。 - 刷新 MCP 服务器列表,确认
couchbase已启用。
**日志:**在底部面板中打开 Output,然后选择 Cursor MCP。
Windsurf Editor
- 打开 Command Palette > Windsurf MCP Configuration Panel,或 Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers(参阅 Windsurf 的 MCP 文档)。
- 点击 Add Server > Add custom server,粘贴配置并保存。
- 刷新服务器列表,确认
couchbase已启用。
VS Code
VS Code 使用 servers 作为顶层键,而不是 mcpServers。对于工作区,将配置放入 .vscode/mcp.json;对于所有工作区,运行 MCP: Open User Configuration(参阅 VS Code 的 MCP 文档):
{
"servers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server", "operational"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
保存文件后服务器即会启动;使用其上方的 Running | Stop | n Tools 操作来管理服务器。
**日志:**运行 MCP: List Servers,选择 couchbase,然后点击 Show Output。
JetBrains IDE
- 安装 AI Assistant 或 Junie 插件。
- 前往 Settings > Tools > AI Assistant (or Junie) > MCP Server,点击 +,添加配置并点击 Apply。
- 将鼠标悬停在服务器状态上即可查看其工具。
**日志:**Help > Show Log in Finder (Explorer) > mcp > couchbase。
Docker
预构建镜像以 couchbase/mcp-server 的名称发布到 Docker Hub,服务器也列在 Docker MCP Catalog 中。使用与上述相同的环境变量配置容器。有关标签、卷和健康检查示例,请参阅 Docker Hub 页面(DOCKER.md)。
通过 HTTP 运行时 — 请注意,服务器必须绑定到 0.0.0.0,才能从容器外部访问:
docker run --rm \
-e CB_CONNECTION_STRING='<couchbase_connection_string>' \
-e CB_USERNAME='<database_user>' \
-e CB_PASSWORD='<database_password>' \
-e CB_MCP_TRANSPORT=http \
-e CB_MCP_HOST=0.0.0.0 \
-p 8000:8000 \
couchbase/mcp-server:latest operational
- 如果 Couchbase 在主机上运行,请将
couchbase://host.docker.internal用作连接字符串(参阅 Docker 网络)。使用--network=<your_network>加入另一个容器的网络。 - 使用
operational-insights替代operational,即可运行 Operational Insights 服务器(端口8001)。
从源代码构建镜像
docker build -t mcp/couchbase-src .
./build.sh [image-name] 使用与 CI 相同的参数进行构建 — 它会设置 GIT_COMMIT_HASH 和 BUILD_DATE 构建参数,并将镜像标记为 latest 和 <short-commit>(默认名称为 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 .
# Check the labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest
故障排除
完整指南请参阅运营服务器和 Operational Insights 服务器的故障排除文档,以及运营服务器和 Operational Insights 服务器的安全指南。快速检查:
- 检查连接字符串、用户名/密码或证书路径。
- 对于 Capella,请确保集群允许连接运行服务器的计算机。
- 确保数据库用户至少可以访问一个存储桶。
- 如果客户端找不到
uv/uvx,请在command中填写绝对路径。 - 从源代码运行时,请检查配置中的仓库路径,并在拉取更新后运行
uv sync。 - 调用
get_server_configuration_status查看服务器实际解析出的配置,并检查客户端日志(参阅客户端设置)。
常见问题
如何将 Claude Desktop 连接到 Couchbase? 将快速入门配置添加到 claude_desktop_config.json 并重启 Claude Desktop — 参阅客户端设置。
可以将它用于 Couchbase Capella 吗? 可以,运营服务器适用于 Capella 和自管理集群,但部分管理工具仅适用于自管理集群(参阅工具)。Operational Insights 服务器仅适用于自管理的 Operational Insights 集群。
允许 AI 代理写入我的数据库安全吗? 默认情况下不安全:不会加载写入工具,并且会阻止修改 SQL++。如果启用写入,仍可禁用单个工具或要求确认 — 但 Couchbase 用户的 RBAC 权限仍是实际的安全边界。参阅安全控制。
我需要了解 SQL++ 吗? 不需要。用日常语言提问,助手会为 run_sql_plus_plus_query 编写 SQL++。它还可以解释查询计划,或向 Index Advisor 请求建议。
使用 STDIO 还是 Streamable HTTP? 单个本地客户端使用 STDIO。要让多个客户端共用一个服务器并使用 OAuth,请使用 Streamable HTTP。参阅传输方式。
Couchbase 是否正式支持此项目? 是,需持有 Couchbase AI Data Plane 许可证。没有许可证时,Couchbase 工程师会通过 GitHub issues 尽力提供帮助。参阅支持政策。
参与贡献
欢迎提交贡献 — 包括错误修复、功能和文档。如需报告错误或寻求帮助,请提交 GitHub issue。
有关开发环境设置、代码检查、测试、项目结构和工作流程,请参阅 CONTRIBUTING.md。开始步骤:
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase
uv sync --extra dev
uv run pre-commit install
./scripts/lint.sh
集成测试会针对运行中的集群执行。导出 CB_CONNECTION_STRING、CB_USERNAME、CB_PASSWORD,并可选地导出 CB_MCP_TEST_BUCKET;Operational Insights 测试还会使用 CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / _USERNAME / _PASSWORD,如果这些变量未设置,则会跳过测试。然后运行:
uv run --extra dev pytest tests/integration -v
使用数据、LLM 风险和支持政策
使用数据收集
本产品会自动收集使用情况和性能数据(例如产品名称和版本)以及浏览器信息(例如 IP 地址)(统称为“使用数据”)。Couchbase 会将使用数据与您可能提供给 Couchbase 的其他数据(例如您的用户名或电子邮件地址)结合使用,以开发和改进我们的产品,并为我们的销售和营销计划提供信息。我们不会访问或收集您存储在 Couchbase 产品中的任何数据。我们使用使用数据来了解总体使用模式,并让我们的产品更好地满足您的需求。有关 Couchbase 如何收集、保护和处理信息的更多信息,请参阅 Couchbase 隐私政策,查看地址为 https://www.couchbase.com/privacy-policy.
与 LLM 相关的风险
- 使用大型语言模型及类似技术存在风险,包括可能产生不准确或有害输出。
- Couchbase 不会审核或评估此类输出的质量或准确性,此类输出也不一定反映 Couchbase 的观点。
- 您须自行决定是否使用大型语言模型及相关技术,并负责遵守适用于您使用这些技术的任何许可条款、使用条款以及您所在组织的政策。
支持政策
Couchbase MCP Server 是由 Couchbase 工程师维护的开源项目。您获取帮助的方式取决于您的使用方式:
- 社区使用 — 通过提交 GitHub issue报告错误、提问和请求功能。Couchbase 工程师会关注代码库,并尽力回复,但不承诺响应时间。Couchbase 支持门户无法为社区使用提供帮助。
- 企业支持 — 可通过许可使用 Couchbase AI Data Plane获得,该许可也涵盖 Couchbase Agent Memory 和 Couchbase Agent Catalog。获得许可的客户可通过常用的 Couchbase 支持渠道获取帮助。
感谢您使用并为本项目做出贡献!