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 License Python 3.11+ PyPI version Install in Cursor Verified on MseeP Trust Score

完整文档:docs.couchbase.com/mcp-server

Couchbase Server MCP server

目录

为什么选择 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 serverOperational 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 端口80008001
默认日志文件mcp_server.logmcp_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-pathmTLS 身份验证
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_reportSDK 缓存的连接诊断信息,不进行主动网络探测
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_metricsManagement REST(/pools/default/stats/range)
get_cluster_tasksManagement REST(/pools/default/tasks)
get_bucket_configManagement REST(/pools/default/buckets[/<name>])
get_cluster_health_snapshotManagement REST,以及每个节点的端点
get_cluster_system_eventsManagement REST(/events)
get_index_statsIndex Service REST(每个索引器的 /api/v1/stats)
get_cluster_query_vitalsQuery service REST(/admin/vitals)
get_active_queriesQuery service REST(/admin/active_requests)
delete_active_queryQuery 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必需可选备注
capellaCB_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 中找到
openaiCB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT设置端点以使用兼容 OpenAI 的本地服务器(Ollama、vLLM、LM Studio)
cohereCB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
voyageCB_MCP_EMBEDDING_MODEL_API_KEY、CB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_ENDPOINT
bedrockCB_MCP_EMBEDDING_MODELCB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID、CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY、CB_MCP_EMBEDDING_MODEL_AWS_REGIONAmazon 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-stringCouchbase 集群的连接字符串必填
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、httpstdio
CB_MCP_HOST--hostHTTP 传输模式的主机127.0.0.1
CB_MCP_PORT--portHTTP 传输模式的端口8000
CB_MCP_WORKERS--workershttp 传输模式的服务器工作进程数。值大于 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-levelMCP 服务器的日志级别: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-mbERROR 日志文件的轮转大小,单位为 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-mbWARNING 日志文件的轮转大小,单位为 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-mbINFO 日志文件的轮转大小,单位为 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-mbDEBUG 日志文件的轮转大小,单位为 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-countERROR 日志文件保留的轮转备份数;覆盖 ERROR 的全局数量继承 CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT--log-warning-retention-backup-countWARNING 日志文件保留的轮转备份数;覆盖 WARNING 的全局数量继承 CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT--log-info-retention-backup-countINFO 日志文件保留的轮转备份数;覆盖 INFO 的全局数量继承 CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT--log-debug-retention-backup-countDEBUG 日志文件保留的轮转备份数;覆盖 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-algorithmJWT 签名算法:可选值为 RS256/384/512、ES256/384/512、PS256/384/512RS256
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 协议使用 stdoutconsole
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-providerrun_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-idAWS 访问密钥 ID,仅适用于 bedrock 提供方。省略时使用默认 AWS 凭证链无
CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY--embedding-model-aws-secret-access-keyAWS 秘密访问密钥,仅适用于 bedrock 提供方无
CB_MCP_EMBEDDING_MODEL_AWS_REGION--embedding-model-aws-regionAWS 区域,仅适用于 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
  1. 打开配置文件(参阅 MCP 快速入门指南):
    • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows:%APPDATA%\Claude\claude_desktop_config.json
  2. 在 mcpServers 下添加服务器,然后重启 Claude Desktop。

**日志:**macOS ~/Library/Logs/Claude,Windows %APPDATA%\Claude\Logs。参阅 MCP 故障排除指南。

Cursor
  1. 前往 Cursor Settings > Tools & Integrations > MCP Tools(参阅 Cursor 的 MCP 文档),或使用一键式在 Cursor 中安装链接 — 然后替换占位连接字符串和凭据。
  2. 在 mcpServers 下添加配置并保存。
  3. 刷新 MCP 服务器列表,确认 couchbase 已启用。

**日志:**在底部面板中打开 Output,然后选择 Cursor MCP。

Windsurf Editor
  1. 打开 Command Palette > Windsurf MCP Configuration Panel,或 Windsurf Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers(参阅 Windsurf 的 MCP 文档)。
  2. 点击 Add Server > Add custom server,粘贴配置并保存。
  3. 刷新服务器列表,确认 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
  1. 安装 AI Assistant 或 Junie 插件。
  2. 前往 Settings > Tools > AI Assistant (or Junie) > MCP Server,点击 +,添加配置并点击 Apply。
  3. 将鼠标悬停在服务器状态上即可查看其工具。

**日志:**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 支持渠道获取帮助。

感谢您使用并为本项目做出贡献!