Couchbase MCP Server

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 客户端也可使用。

配置

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

MCP 客户端的服务器配置

这是 Claude Desktop、Cursor、Windsurf Editor 等 MCP 客户端的常见配置。

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

• 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 客户端

1. 现在可以通过编辑配置文件将 MCP 服务器添加到 Claude Desktop。更多详细说明请参阅MCP 快速入门指南。
   • 在 Mac 上，配置文件位于~/Library/Application Support/Claude/claude_desktop_config.json
   • 在 Windows 上，配置文件位于%APPDATA%\Claude\claude_desktop_config.json

   打开配置文件并将配置添加到mcpServers部分。

2. 重新启动 Claude Desktop 以应用更改。
3. 您现在可以使用 Claude Desktop 中的服务器使用自然语言在 Couchbase 集群上运行查询并对文档执行 CRUD 操作。

Claude 桌面日志

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

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

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

光标

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

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

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

游标日志

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

风帆冲浪编辑

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

1. 在您的机器上安装Windsurf Editor 。
2. 在 Windsurf 编辑器中，导航至“命令面板”>“Windsurf MCP 配置面板”，或“Windsurf - 设置”>“高级”>“级联”>“模型上下文协议 (MCP) 服务器”。更多配置详情，请参阅官方文档。
3. 点击“添加服务器”，然后点击“添加自定义服务器”。在编辑器中打开的配置中，添加上面的 Couchbase MCP 服务器配置。
4. 保存配置。
5. 您将在“高级设置”下的“MCP 服务器”列表中看到 Couchbase 服务器已添加。刷新查看服务器是否已启用。
6. 您现在可以使用 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上找到预构建的镜像。

跑步

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

法学硕士相关风险

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

托管 MCP 服务器

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

故障排除提示

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

📢 支持政策

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

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

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