Couchbase MCP 服务器

Couchbase 的MCP服务器实现，允许 LLM 直接与 Couchbase 集群交互。

特征

获取指定 bucket 中所有 scopes 和 collections 的列表
获取集合的结构
从指定范围和集合中按 ID 获取文档
根据 ID 将文档插入到指定的范围和集合
根据 ID 从指定范围和集合中删除文档
在指定范围内运行SQL++ 查询
- MCP 服务器中有一个选项READ_ONLY_QUERY_MODE ，默认设置为 true，以禁用会更改数据或底层集合结构的 SQL++ 查询。请注意，文档仍然可以通过 ID 进行更新。

先决条件

Python 3.10 或更高版本。
一个正在运行的 Couchbase 集群。最简单的入门方法是使用Capella免费套餐，它是 Couchbase 服务器的完全托管版本。您可以按照说明导入示例数据集之一，也可以导入您自己的数据集。
uv安装以运行服务器。
安装一个MCP 客户端（例如Claude Desktop），用于将服务器连接到 Claude。本指南针对 Claude Desktop 和 Cursor 提供。其他 MCP 客户端也可使用。

配置

将存储库克隆到本地机器。

git clone https://github.com/Couchbase-Ecosystem/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",
        "CB_BUCKET_NAME": "bucket_name"
      }
    }
  }
}

可以使用环境变量配置服务器。支持以下变量：

CB_CONNECTION_STRING ：Couchbase 集群的连接字符串
CB_USERNAME ：具有用于连接的存储桶访问权限的用户名
CB_PASSWORD ：连接用户名的密码
CB_BUCKET_NAME ：服务器将访问的存储桶的名称
READ_ONLY_QUERY_MODE ：设置是否允许修改数据的 SQL++ 查询。默认设置为 True。
path/to/cloned/repo/mcp-server-couchbase/应该是您本地机器上克隆仓库的路径。别忘了末尾的斜杠！

注意：如果您在客户端中使用其他 MCP 服务器，您可以将其添加到现有的mcpServers对象中。

克劳德桌面

按照以下步骤使用 Couchbase MCP 服务器和 Claude Desktop MCP 客户端

现在可以通过编辑配置文件将 MCP 服务器添加到 Claude Desktop。更多详细说明请参阅MCP 快速入门指南。
- 在 Mac 上，配置文件位于~/Library/Application Support/Claude/claude_desktop_config.json
- 在 Windows 上，配置文件位于%APPDATA%\Claude\claude_desktop_config.json
打开配置文件并将配置添加到mcpServers部分。
重新启动 Claude Desktop 以应用更改。
您现在可以使用 Claude Desktop 中的服务器使用自然语言在 Couchbase 集群上运行查询并对文档执行 CRUD 操作。

Claude 桌面日志

您可以在以下位置找到 Claude Desktop 的日志：

MacOS：~/Library/Logs/Claude
Windows：%APPDATA%\Claude\Logs

这些日志可用于诊断连接问题或其他 MCP 服务器配置问题。更多详情，请参阅官方文档。

光标

按照以下步骤将 Couchbase MCP 服务器与 Cursor 结合使用：

在您的机器上安装Cursor 。
在 Cursor 中，前往“Cursor”>“Cursor 设置”>“MCP”>“添加新的全局 MCP 服务器”。此外，请查看 Cursor 中关于设置 MCP 服务器配置的文档。
指定相同的配置。您可能需要在 mcpServers 的父键下添加服务器配置。
保存配置。
您将在 MCP 服务器列表中看到 Couchbase 服务器已添加。刷新查看服务器是否已启用。
您现在可以使用 Cursor 中的 Couchbase MCP 服务器，通过自然语言查询您的 Couchbase 集群并对文档执行 CRUD 操作。

有关 MCP 与 Cursor 集成的更多详细信息，请参阅官方 Cursor MCP 文档。

游标日志

在 Cursor 底部面板中，点击“输出”，然后从下拉菜单中选择“Cursor MCP”以查看服务器日志。这有助于诊断连接问题或其他 MCP 服务器配置问题。

风帆冲浪编辑

按照以下步骤将 Couchbase MCP 服务器与Windsurf Editor一起使用。

在您的机器上安装Windsurf Editor 。
在 Windsurf 编辑器中，导航至“命令面板”>“Windsurf MCP 配置面板”，或“Windsurf - 设置”>“高级”>“级联”>“模型上下文协议 (MCP) 服务器”。更多配置详情，请参阅官方文档。
点击“添加服务器”，然后点击“添加自定义服务器”。在编辑器中打开的配置中，添加上面的 Couchbase MCP 服务器配置。
保存配置。
您将在“高级设置”下的“MCP 服务器”列表中看到 Couchbase 服务器已添加。刷新查看服务器是否已启用。
您现在可以使用 Windsurf Editor 中的 Couchbase MCP 服务器，通过自然语言查询您的 Couchbase 集群并对文档执行 CRUD 操作。

有关 MCP 与 Windsurf Editor 集成的更多详细信息，请参阅官方Windsurf MCP 文档。

SSE 服务器模式

有一个选项可以在服务器发送事件 (SSE)传输模式下运行 MCP 服务器。

用法

默认情况下，MCP 服务器将在端口 8080 上运行，但可以使用FASTMCP_PORT环境变量进行配置。

uv 运行 src/mcp_server.py --connection-string='<couchbase_connection_string>' --username='<database_username>' --password='<database_password>' --bucket-name='<couchbase_bucket_to_use>' --read-only-query-mode=true --transport=sse

服务器将在http://localhost:8080/sse上可用。这可以在支持 SSE 传输模式的 MCP 客户端中使用。

Docker 镜像

MCP 服务器也可以以 Docker 容器的形式构建和运行。您可以在DockerHub上找到预构建的镜像。

docker built -t mcp/couchbase .

跑步

MCP 服务器可以与用于配置 Couchbase 设置的环境变量一起运行。环境变量与配置部分中描述的相同。

docker run -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_BUCKET_NAME='<bucket_name>' \
  -e MCP_TRANSPORT='stdio/sse' \
  -e READ_ONLY_QUERY_MODE="true/false" \
  mcp/couchbase

法学硕士相关风险

使用大型语言模型和类似技术存在风险，包括可能产生不准确或有害的输出。
Couchbase 不会审查或评估此类输出的质量或准确性，并且此类输出可能无法反映 Couchbase 的观点。
您应全权负责确定是否使用大型语言模型和相关技术，并负责遵守任何许可条款、使用条款以及您所在组织管理您使用这些技术的政策。

托管 MCP 服务器

Couchbase MCP 服务器还可以通过Smithery.ai用作代理应用程序中的托管服务器。

故障排除提示

确保配置中 MCP 服务器存储库的路径正确。
验证您的 Couchbase 连接字符串、数据库用户名、密码和存储桶名称是否正确。
如果使用 Couchbase Capella，请确保可以从运行 MCP 服务器的机器访问该集群。
检查数据库用户是否具有访问指定存储桶的适当权限。
确认 uv 包管理器已正确安装并可访问。您可能需要在配置的command字段中提供 uv 的绝对路径。
检查日志中是否存在任何可能表明 MCP 服务器存在问题的错误或警告。服务器日志位于mcp-server-couchbase.log下。

📢 支持政策

我们非常感谢您对这个项目的关注！
该项目由社区维护，这意味着它不受我们的支持团队的官方支持。

如果您需要帮助、发现了错误或想要做出改进，最好的地方就是这里 — — 通过打开 GitHub 问题。
我们的支持门户无法协助处理与该项目相关的请求，因此我们恳请所有查询都保留在 GitHub 内。

您的合作有助于我们共同前进——谢谢！

Couchbase MCP Server

Integrations