couchbaseecosystem/couchbase-guru repository overview

⁠Couchbase Guru MCP Server

An MCP⁠ server that lets LLMs search the Couchbase documentation⁠ from your MCP client. It exposes a single tool, ask_couchbase_docs, which forwards your question to a hosted retrieval-augmented (RAG) documentation agent and returns an answer with source links.

⁠Tool

Ask complete, self-contained questions — the backend has no conversation history, so include the product, version, and language where relevant (e.g. "How do I create a primary index with the Python SDK in Couchbase Server 7.6?").

⁠Prerequisites

• Python 3.10 or higher.
• uv⁠ installed to run the server.
• An MCP client⁠ such as Claude Desktop⁠, Cursor⁠, or VS Code⁠.

⁠Configuration

The server can be run from the prebuilt PyPI package or from source with uv. It works with zero configuration — the public documentation agent is used by default.

⁠Running from PyPI

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

⁠Running from Source

Clone the repository:

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

Then point your MCP client at it:

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

⁠Options

All options are optional and can be set via CLI argument or environment variable:

Check the installed version with:

uvx couchbase-guru --version

⁠Self-hosting the documentation agent

By default the server uses a shared, public documentation agent, so most users need no setup. If you run your own agent backend, point the server at it:

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

⁠Rate limiting & privacy

The public agent applies fair-use rate limits. To support this, the server sends a pseudonymous device identifier to the backend (in the User-Agent header):

• stdio: a random id generated once and stored in a per-user file on your machine.
• HTTP: a salted, one-way hash of the connecting IP — the raw address is never sent.

No question content or personal data is persisted by the MCP server itself. If you prefer not to share a rate-limit signal, self-host the agent (see above).

⁠Client-specific configuration

⁠Streamable HTTP transport mode

The server can run in Streamable HTTP⁠ mode so multiple clients can connect to one instance. Check that your MCP client supports this transport first.

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

The server will be available at http://localhost:8000/mcp⁠:

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

⁠Docker

Build the image:

docker build -t couchbase-guru .

Run it (stdio by default; no credentials needed):

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

For HTTP transport, publish the port and set the transport:

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

⁠Risks associated with LLMs

• The use of large language models and similar technology involves risks, including the potential for inaccurate or harmful outputs.
• Couchbase does not review or evaluate the quality or accuracy of such outputs, and such outputs may not reflect Couchbase's views.
• You are solely responsible for determining whether to use large language models and related technology, and for complying with any applicable license terms, terms of use, and your organization's policies.

⁠Troubleshooting

• Confirm that uv/uvx is installed and on your PATH. You may need to provide an absolute path to uv/uvx in the command field.
• If a search times out, the documentation backend may be busy — retry in a moment.
• To rule out the public backend, run against your own agent with --agent-base-url.
• If running from source after updating the repo, run uv sync to refresh dependencies.
• Check your MCP client's logs (locations above) for errors.

⁠Testing

Unit tests run offline (the backend is mocked):

uv sync --extra dev
uv run pytest tests/

Integration tests exercise the tool end-to-end against a live agent backend and are opt-in:

CB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py

By default they use the public agent; set CB_AGENT_BASE_URL to target a different backend.

⁠👩‍💻 Contributing

Contributions are welcome! To report a bug, request a feature, or contribute improvements, open a GitHub issue⁠.

See CONTRIBUTING.md⁠ for developer setup (environment with uv, linting/formatting with Ruff, pre-commit hooks, and project structure).

# 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

⁠📢 Support Policy

We appreciate your interest in this project! It is Couchbase community-maintained, which means it is not officially supported by our support team. Our engineers monitor and maintain this repo and will try to resolve issues on a best-effort basis. Please keep all inquiries within GitHub.