Couchbase Guru MCP Server

一个 MCP 服务器，允许 LLM 从你的 MCP 客户端搜索 Couchbase 文档。它提供一个单一工具 ask_couchbase_docs，该工具会将你的问题转发给托管的检索增强生成（RAG）文档代理，并返回带来源链接的答案。

无需 Couchbase 集群或凭据。 服务器仅与文档代理后端通信，不接触你的数据。

工具

请提出完整、自包含的问题——后端没有对话历史，因此在相关时请注明产品、版本和语言（例如 “如何在 Couchbase Server 7.6 中使用 Python SDK 创建主索引？”）。

Related MCP server: docrag

先决条件

• Python 3.10 或更高版本。

• 已安装 uv 以运行服务器。

• 一个 MCP 客户端，例如 Claude Desktop、Cursor 或 VS Code。

配置

服务器可以从预构建的 PyPI 包运行，也可以使用 uv 从源码运行。它零配置即可工作——默认使用公共文档代理。

从 PyPI 运行

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uvx",
      "args": ["couchbase-guru"]
    }
  }
}

如果你已经配置了其他 MCP 服务器，请将此条目添加到现有的 mcpServers 对象中。

从源码运行

克隆仓库：

git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git

然后将你的 MCP 客户端指向它：

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/couchbase-guru/",
        "run",
        "src/mcp_server.py"
      ]
    }
  }
}

path/to/cloned/repo/couchbase-guru/ 应该是你机器上克隆仓库的路径。不要忘记末尾的斜杠。

选项

所有选项都是可选的，可以通过 CLI 参数或环境变量设置：

使用以下命令检查已安装的版本：

uvx couchbase-guru --version

自托管文档代理

默认情况下，服务器使用共享的公共文档代理，因此大多数用户无需设置。如果你运行自己的代理后端，请将服务器指向它：

uvx couchbase-guru --agent-base-url https://your-agent.example.com

速率限制与隐私

公共代理会执行公平使用的速率限制。为支持这一点，服务器会向后端发送一个假名化的设备标识符（位于 User-Agent 头中）：

• stdio：一次性生成的随机 ID，存储在你机器上的一个按用户区分的文件中。

• HTTP：连接 IP 的加盐单向哈希——原始地址永远不会被发送。

MCP 服务器本身不会持久化任何问题内容或个人数据。如果你不希望共享速率限制信号，可以自托管代理（见上文）。

客户端特定配置

1. 编辑配置文件（参见 MCP 快速入门指南）：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 将配置添加到 mcpServers 部分。

3. 重启 Claude Desktop。

日志：~/Library/Logs/Claude（macOS）或 %APPDATA%\Claude\Logs（Windows）。

1. 在 Cursor 中，转到 Cursor 设置 > 工具与集成 > MCP 工具。

2. 手动添加配置，或使用一键式在 Cursor 中安装链接。

3. 保存，然后刷新以确认服务器已启用。

日志：在底部面板中，单击 输出，然后从下拉菜单中选择 Cursor MCP。

1. 打开命令面板 > Windsurf MCP 配置面板（或设置 > 高级 > Cascade > 模型上下文协议（MCP）服务器）。

2. 单击添加服务器 > 添加自定义服务器，并添加配置。

3. 保存，然后刷新以确认服务器已启用。

有关详细信息，请参阅 Windsurf MCP 文档。

1. 在你的工作区中创建 .vscode/mcp.json（或运行 MCP：打开用户配置 以进行全局配置）。

2. VS Code 使用 servers 作为顶级键（而不是 mcpServers）：

   {
     "servers": {
       "couchbase-guru": {
         "command": "uvx",
         "args": ["couchbase-guru"]
       }
     }
   }

3. 保存后，使用内联操作列表来 Start/Stop/管理服务器。

有关详细信息，请参阅 VS Code MCP 文档。

1. 安装 AI Assistant 或 Junie 插件。

2. 导航到 设置 > 工具 > AI Assistant 或 Junie > MCP 服务器。

3. 单击“+”，添加配置，然后依次单击保存和应用。

日志：帮助 > 在 Finder（资源管理器）中显示日志 > mcp > couchbase-guru。

Streamable HTTP 传输模式

服务器可以在 Streamable HTTP 模式下运行，以便多个客户端可以连接到同一个实例。请先确认你的 MCP 客户端支持此传输方式。

uvx couchbase-guru --transport=http --port=8000

服务器将在 http://localhost:8000/mcp 上可用：

{
  "mcpServers": {
    "couchbase-guru-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

此模式不包含授权支持。

Docker

构建镜像：

docker build -t couchbase-guru .

运行它（默认为 stdio；无需凭据）：

{
  "mcpServers": {
    "couchbase-guru-docker": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "couchbase-guru"]
    }
  }
}

对于 HTTP 传输，请发布端口并设置传输方式：

docker run --rm -i \
  -e CB_MCP_TRANSPORT=http \
  -e CB_MCP_HOST=0.0.0.0 \
  -e CB_MCP_PORT=8000 \
  -p 8000:8000 \
  couchbase-guru

与 LLM 相关的风险

• 使用大型语言模型及类似技术存在风险，包括可能产生不准确或有害的输出。

• Couchbase 不会审查或评估此类输出的质量或准确性，此类输出也可能不反映 Couchbase 的观点。

• 你全权负责决定是否使用大型语言模型及相关技术，并遵守任何适用的许可条款、使用条款以及你所在组织的政策。

故障排除

• 确认 uv/uvx 已安装并位于你的 PATH 中。你可能需要在 command 字段中提供 uv/uvx 的绝对路径。

• 如果搜索超时，文档后端可能正忙——请稍后重试。

• 要排除公共后端，请使用 --agent-base-url 针对你自己的代理运行。

• 如果在更新仓库后从源码运行，请运行 uv sync 以刷新依赖。

• 检查你的 MCP 客户端的日志（位置见上文）以查找错误。

测试

单元测试离线运行（后端被模拟）：

uv sync --extra dev
uv run pytest tests/

集成测试针对实时代理后端对工具进行端到端测试，并且是可选择启用的：

CB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py

默认情况下，它们使用公共代理；设置 CB_AGENT_BASE_URL 可指向不同的后端。

👩💻 贡献

欢迎贡献！要报告错误、请求功能或贡献改进，请打开 GitHub Issue。

开发者设置（使用 uv 的环境、使用 Ruff 进行 lint/格式化、pre-commit 钩子以及项目结构）请参阅 CONTRIBUTING.md。

# Clone and set up
git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git
cd couchbase-guru

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

📢 支持政策

感谢你对此项目的关注！它是 Couchbase 社区维护的项目，这意味着我们的支持团队不提供官方支持。我们的工程师会监控并维护此仓库，并会尽最大努力解决问题。请将所有咨询保留在 GitHub 内。