de en es ja ko ru zh

Couchbase Guru MCP Server

Name: Couchbase Guru MCP Server
Author: Couchbase-Ecosystem

by Couchbase-Ecosystem

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Couchbase Guru MCP Server

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

License Python 3.10+ PyPI version

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

工具

工具名称	描述
`ask_couchbase_docs`	通过搜索官方文档，回答有关任何 Couchbase 产品、功能、SDK、服务、教程或示例的问题。返回自然语言答案，并附上文档来源 URL。

请提出完整、自包含的问题——后端没有对话历史，因此在相关时请注明产品、版本和语言（例如 “如何在 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 参数或环境变量设置：

CLI 参数	环境变量	描述	默认值
`--transport`	`CB_MCP_TRANSPORT`	传输模式：`stdio` 或 `http`	`stdio`
`--host`	`CB_MCP_HOST`	HTTP 传输模式的主机	`127.0.0.1`
`--port`	`CB_MCP_PORT`	HTTP 传输模式的端口	`8000`
`--agent-base-url`	`CB_AGENT_BASE_URL`	文档代理后端的基础 URL。设置此项可针对你自己托管的代理运行；如果未设置，则使用公共代理。	公共代理
`--agent-ip-salt`	`CB_AGENT_IP_SALT`	用于对客户端 IP 进行假名化的秘密盐值（HTTP 传输）。设置一个共享值，以便在多个实例间保持一致的哈希；未设置时会生成一个本地盐值。	自动生成

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

uvx couchbase-guru --version

自托管文档代理

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

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

速率限制与隐私

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

stdio：一次性生成的随机 ID，存储在你机器上的一个按用户区分的文件中。
HTTP：连接 IP 的加盐单向哈希——原始地址永远不会被发送。

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

客户端特定配置

编辑配置文件（参见 MCP 快速入门指南）：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
将配置添加到 mcpServers 部分。
重启 Claude Desktop。

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

在 Cursor 中，转到 Cursor 设置 > 工具与集成 > MCP 工具。
手动添加配置，或使用一键式在 Cursor 中安装链接。
保存，然后刷新以确认服务器已启用。

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

打开命令面板 > Windsurf MCP 配置面板（或设置 > 高级 > Cascade > 模型上下文协议（MCP）服务器）。
单击添加服务器 > 添加自定义服务器，并添加配置。
保存，然后刷新以确认服务器已启用。

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

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

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

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

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

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

安装 AI Assistant 或 Junie 插件。
导航到 设置 > 工具 > AI Assistant 或 Junie > MCP 服务器。
单击“+”，添加配置，然后依次单击保存和应用。

日志：帮助 > 在 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 内。

Available Tools

1 tool

ask_couchbase_docsA

Read-only

Search Couchbase documentation to answer questions about any Couchbase product, feature, SDK, service, tutorials or examples. Use this tool for all Couchbase how-to, conceptual, and reference questions. Not for direct cluster operations.

Name	Required	Description	Default
`question`	Yes	A complete, self-contained question about Couchbase products, SDKs, or services. Must include necessary context like product name, version, or programming language since the agent called by this tool lacks conversation history.

Output Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already signals a safe, read-only operation, so the description does not need to re-prove that. It adds a useful scope boundary ('Not for direct cluster operations') but does not disclose extra behavioral details such as response format or failure modes. With annotations covering safety, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences plus one exclusion clause, with no filler. The primary action and supported scope are front-loaded, and every sentence contributes useful routing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with a detailed schema and an output schema available, the description is complete: it states scope, gives explicit usage guidance, and excludes the one class of out-of-scope requests. Nothing critical is missing for an agent to decide whether and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the question parameter is already well-described with guidance to make it self-contained and include product/version/language context. The tool description itself adds no parameter-level meaning, but with full schema coverage the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Search Couchbase documentation') and a clear resource, then enumerates the scope of supported topics (products, features, SDKs, services, tutorials, examples). It is immediately obvious what this tool does and where it differs from cluster-operation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use this tool for all Couchbase how-to, conceptual, and reference questions. Not for direct cluster operations' provides an explicit when-to-use and an explicit when-not-to-use. An agent can route questions correctly without needing sibling-tool descriptions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

1 tool updatev0.1.0Aug 28, 2026
- First observedask_couchbase_docs

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-08-28 00:50 across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap. The tool's purpose is singular and clearly described.

Naming Consistency5/5

The single tool name 'ask_couchbase_docs' follows a clear verb_noun pattern, which is internally consistent by default.

Tool Count4/5

One tool is perfectly matched to the narrow docs-Q&A scope, though it is on the thin side relative to typical MCP servers.

Completeness5/5

The tool's description explicitly covers all Couchbase documentation questions, leaving no obvious gaps within the stated scope.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

agentready-mcp A
io.github.AshutoshRaj97
Query any docs site via MCP. Submit a URL, ask questions, get cited answers.
Documentation Access Search
822
https://www.agentready.it.com/api/mcp
docs2mcpOAuth
com.docs2mcp
Query your own PDFs and documents from any MCP client. Every answer cites the page it came from.
RAG Systems Search
1
https://mcp.docs2mcp.com/mcp
forkast-mcp-docs A
io.github.ForkastPredict
MCP server for querying Forkast documentation
Documentation Access Search Developer Tools
42
https://mcp.forkast.gg/mcp
Dewey
com.meetdewey
Agentic search over your Dewey document collections from any MCP-compatible client.
Search Knowledge & Memory RAG Systems
2
https://mcp.meetdewey.com/mcp

Related MCP Servers

Markdown RAG MCP
RAG Systems Search
mohllal
A
license
Not graded
quality
D
maintenance
Provides semantic search over markdown documentation using RAG, allowing natural language queries and integration with MCP clients.
Updated a year ago (2025-10-23 22:41 UTC)
1
MIT
docrag
RAG Systems Documentation Access
ryan-m-bishop
A
license
Not graded
quality
F
maintenance
Provides RAG (Retrieval Augmented Generation) access to technical documentation through MCP, enabling LLMs to search and retrieve relevant documentation on-demand.
Updated 10 months ago (2026-01-13 15:18 UTC)
5
MIT
faq-rag
RAG Systems Search
chowgi
F
license
Not graded
quality
D
maintenance
Enables answering natural-language questions from FAQ documents using vector search and LLM generation via an MCP tool.
Updated 8 months ago (2026-02-17 10:02 UTC)
-
doc-mcp
RAG Systems Search
tirth1263
F
license
Not graded
quality
D
maintenance
Enables semantic search and AI-powered Q&A over ingested GitHub documentation repositories via MCP tools.
Updated 4 months ago (2026-06-30 01:56 UTC)
-

Couchbase Guru MCP Server

工具

先决条件

配置

从 PyPI 运行

从源码运行

选项

自托管文档代理

速率限制与隐私

客户端特定配置

Streamable HTTP 传输模式

Docker

与 LLM 相关的风险

故障排除

测试

👩💻 贡献

📢 支持政策

Available Tools

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Markdown RAG MCP

docrag

faq-rag

doc-mcp