使用说明

项目简介

Couchbase MCP 服务器是一个实现了 Model Context Protocol (MCP) 协议的服务端应用，它充当 LLM（大型语言模型）客户端与 Couchbase 数据库之间的桥梁。通过该服务器，LLM 可以安全、便捷地访问 Couchbase 中的数据，并执行预定义的操作，例如查询数据库信息、获取集合结构以及运行 SQL++ 查询。

主要功能点

获取 Scope 和 Collection 列表: 允许 LLM 获取指定 Couchbase Bucket 中所有 Scope 和 Collection 的名称，帮助 LLM 理解数据库的组织结构。
获取 Collection 结构: 支持 LLM 获取指定 Collection 的 Schema 信息，从而更好地理解数据字段和类型。
执行 SQL++ 查询: 允许 LLM 运行 SQL++ (SQL for Documents) 查询语句，从 Couchbase 数据库中检索数据，并将结果以 JSON 格式返回。

安装步骤

克隆仓库

git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git
cd mcp-server-couchbase

安装 Python 依赖 确保你的 Python 版本为 3.10 或更高。建议使用 'uv' 包管理器运行服务器。如果尚未安装 'uv'，请按照 uv 安装指南进行安装。

服务器配置

要将 Couchbase MCP 服务器与 MCP 客户端（如 Claude Desktop 或 Cursor）连接，您需要在客户端的配置文件中添加服务器配置信息。以下是配置示例，您需要根据您的实际环境进行调整。

对于 Claude Desktop:

编辑 Claude Desktop 的配置文件 ('claude_desktop_config.json')，通常位于：

macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%\Claude\claude_desktop_config.json'

在 'mcpServers' 部分添加如下配置：

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "您的仓库路径",  //  请替换为克隆仓库的本地绝对路径，例如 "/Users/yourname/mcp-server-couchbase/"
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "您的 Couchbase 连接字符串", // 例如 "couchbases://<your_cluster_ip>"
        "CB_USERNAME": "您的 Couchbase 用户名",        // 具有访问 Bucket 权限的用户名
        "CB_PASSWORD": "您的 Couchbase 密码",        // 用户名对应的密码
        "CB_BUCKET_NAME": "您的 Bucket 名称"         //  要访问的 Bucket 名称
      }
    }
  }
}

配置参数说明:

'server name': 服务器名称，这里设置为 "couchbase"，用于在 MCP 客户端中标识该服务器。
'command': 启动服务器的命令，这里使用 'uv' 运行 Python 脚本。
'args': 传递给 'command' 的参数列表。
- '--directory': 指定服务器代码所在的目录。请务必将其替换为克隆仓库的本地绝对路径，并确保路径末尾包含斜杠 '/'。
- 'run src/mcp_server.py': 运行 'src/mcp_server.py' 脚本启动服务器。
'env': 设置服务器运行所需的环境变量。
- 'CB_CONNECTION_STRING': Couchbase 集群的连接字符串，用于连接到您的 Couchbase 数据库。
- 'CB_USERNAME': 用于连接 Couchbase 数据库的用户名。
- 'CB_PASSWORD': 与用户名对应的密码。
- 'CB_BUCKET_NAME': 服务器将要访问的 Couchbase Bucket 的名称。

对于 Cursor:

在 Cursor 中，进入 "Cursor Settings" -> "MCP" -> "Add a new global MCP server"，然后添加与 Claude Desktop 相同的配置信息。

基本使用方法

启动 MCP 服务器: 当您在 MCP 客户端 (Claude Desktop 或 Cursor) 中配置并启用 Couchbase MCP 服务器后，服务器将会在后台启动。
在 LLM 中使用: 在 Claude Desktop 或 Cursor 等 MCP 客户端中，您可以像平常一样与 LLM 对话。当 LLM 需要访问 Couchbase 数据库时，它将自动调用 Couchbase MCP 服务器提供的工具。
自然语言查询: 您可以使用自然语言向 LLM 提出关于 Couchbase 数据库的问题，例如：
- "列出所有可用的数据库集合"
- "获取 'travel-sample' 集合的结构"
- "查询 'travel-sample' 集合中 'United States' 的酒店"

LLM 将会解析您的请求，并调用相应的 MCP 工具来执行数据库操作，最终将结果返回给您。

注意事项

确保您已安装 Python 3.10 或更高版本，并安装了 'uv' 包管理器（推荐）。
仔细检查配置文件中的路径、连接字符串、用户名、密码和 Bucket 名称是否正确。
确保 Couchbase 集群可以从运行 MCP 服务器的机器上访问。
查看服务器日志 ('mcp-server-couchbase.log' 或 MCP 客户端的日志输出) 以诊断连接或配置问题。

关键词