{
  "markdown": "# Couchbase Guru MCP Server\n\nAn [MCP](https://modelcontextprotocol.io/) server that lets LLMs search the [Couchbase documentation](https://docs.couchbase.com/) 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.\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![PyPI version](https://badge.fury.io/py/couchbase-guru.svg)](https://pypi.org/project/couchbase-guru/)\n\n<!-- mcp-name: io.github.Couchbase-Ecosystem/couchbase-guru -->\n\n> **No Couchbase cluster or credentials required.** The server talks only to the documentation agent backend, not to your data.\n\n## Tool\n\n| Tool Name | Description |\n| --------- | ----------- |\n| `ask_couchbase_docs` | Answer a question about any Couchbase product, feature, SDK, service, tutorial, or example by searching the official documentation. Returns a natural-language answer followed by the documentation source URLs. |\n\nAsk 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?\"_).\n\n## Prerequisites\n\n- Python 3.10 or higher.\n- [uv](https://docs.astral.sh/uv/) installed to run the server.\n- An [MCP client](https://modelcontextprotocol.io/clients) such as [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.sh/), or [VS Code](https://code.visualstudio.com/).\n\n## Configuration\n\nThe 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.\n\n### Running from PyPI\n\n```json\n{\n  \"mcpServers\": {\n    \"couchbase-guru\": {\n      \"command\": \"uvx\",\n      \"args\": [\"couchbase-guru\"]\n    }\n  }\n}\n```\n\n> If you already have other MCP servers configured, add this entry to the existing `mcpServers` object.\n\n### Running from Source\n\nClone the repository:\n\n```bash\ngit clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git\n```\n\nThen point your MCP client at it:\n\n```json\n{\n  \"mcpServers\": {\n    \"couchbase-guru\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"path/to/cloned/repo/couchbase-guru/\",\n        \"run\",\n        \"src/mcp_server.py\"\n      ]\n    }\n  }\n}\n```\n\n> `path/to/cloned/repo/couchbase-guru/` should be the path to the cloned repository on your machine. Don't forget the trailing slash.\n\n### Options\n\nAll options are optional and can be set via CLI argument or environment variable:\n\n| CLI Argument | Environment Variable | Description | Default |\n| ------------ | -------------------- | ----------- | ------- |\n| `--transport` | `CB_MCP_TRANSPORT` | Transport mode: `stdio` or `http` | `stdio` |\n| `--host` | `CB_MCP_HOST` | Host for HTTP transport mode | `127.0.0.1` |\n| `--port` | `CB_MCP_PORT` | Port for HTTP transport mode | `8000` |\n| `--agent-base-url` | `CB_AGENT_BASE_URL` | Base URL of the documentation agent backend. Set this to run against your own self-hosted agent; if unset, the public agent is used. | Public agent |\n| `--agent-ip-salt` | `CB_AGENT_IP_SALT` | Secret salt used to pseudonymize client IPs (HTTP transport). Set a shared value for consistent hashing across multiple instances; a local salt is generated when unset. | Auto-generated |\n\nCheck the installed version with:\n\n```bash\nuvx couchbase-guru --version\n```\n\n## Self-hosting the documentation agent\n\nBy 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:\n\n```bash\nuvx couchbase-guru --agent-base-url https://your-agent.example.com\n```\n\n## Rate limiting & privacy\n\nThe 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):\n\n- **stdio**: a random id generated once and stored in a per-user file on your machine.\n- **HTTP**: a salted, one-way hash of the connecting IP — the raw address is never sent.\n\nNo 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).\n\n## Client-specific configuration\n\n<details>\n<summary>Claude Desktop</summary>\n\n1. Edit the configuration file (see the [MCP quickstart guide](https://modelcontextprotocol.io/quickstart/user)):\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n2. Add the [configuration](#running-from-pypi) to the `mcpServers` section.\n3. Restart Claude Desktop.\n\nLogs: `~/Library/Logs/Claude` (macOS) or `%APPDATA%\\Claude\\Logs` (Windows).\n\n</details>\n\n<details>\n<summary>Cursor</summary>\n\n1. In Cursor, go to **Cursor Settings > Tools & Integrations > MCP Tools**.\n2. Add the [configuration](#running-from-pypi) manually, or use the one-click [Install in Cursor][cursor-install-basic] link.\n3. Save, then refresh to confirm the server is enabled.\n\n[cursor-install-basic]: https://cursor.com/en-US/install-mcp?name=couchbase-guru&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJjb3VjaGJhc2UtZ3VydSJdfQ%3D%3D\n\nLogs: in the bottom panel, click **Output** and select **Cursor MCP** from the dropdown.\n\n</details>\n\n<details>\n<summary>Windsurf Editor</summary>\n\n1. Open **Command Palette > Windsurf MCP Configuration Panel** (or **Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers**).\n2. Click **Add Server > Add custom server** and add the [configuration](#running-from-pypi).\n3. Save, then refresh to confirm the server is enabled.\n\nSee the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) for details.\n\n</details>\n\n<details>\n<summary>VS Code</summary>\n\n1. Create `.vscode/mcp.json` in your workspace (or run **MCP: Open User Configuration** for a global config).\n2. VS Code uses `servers` as the top-level key (not `mcpServers`):\n\n   ```json\n   {\n     \"servers\": {\n       \"couchbase-guru\": {\n         \"command\": \"uvx\",\n         \"args\": [\"couchbase-guru\"]\n       }\n     }\n   }\n   ```\n\n3. Once saved, use the inline action list to `Start`/`Stop`/manage the server.\n\nSee the [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for details.\n\n</details>\n\n<details>\n<summary>JetBrains IDEs</summary>\n\n1. Install the [AI Assistant](https://www.jetbrains.com/help/ai-assistant/getting-started-with-ai-assistant.html) or [Junie](https://www.jetbrains.com/help/junie/get-started-with-junie.html) plugin.\n2. Navigate to **Settings > Tools > AI Assistant or Junie > MCP Server**.\n3. Click \"+\", add the [configuration](#running-from-pypi), and click **Save**, then **Apply**.\n\nLogs: **Help > Show Log in Finder (Explorer) > mcp > couchbase-guru**.\n\n</details>\n\n## Streamable HTTP transport mode\n\nThe server can run in [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) mode so multiple clients can connect to one instance. Check that your MCP client supports this transport first.\n\n```bash\nuvx couchbase-guru --transport=http --port=8000\n```\n\nThe server will be available at <http://localhost:8000/mcp>:\n\n```json\n{\n  \"mcpServers\": {\n    \"couchbase-guru-http\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n> This mode does not include authorization support.\n\n## Docker\n\nBuild the image:\n\n```bash\ndocker build -t couchbase-guru .\n```\n\nRun it (stdio by default; no credentials needed):\n\n```json\n{\n  \"mcpServers\": {\n    \"couchbase-guru-docker\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"couchbase-guru\"]\n    }\n  }\n}\n```\n\nFor HTTP transport, publish the port and set the transport:\n\n```bash\ndocker run --rm -i \\\n  -e CB_MCP_TRANSPORT=http \\\n  -e CB_MCP_HOST=0.0.0.0 \\\n  -e CB_MCP_PORT=8000 \\\n  -p 8000:8000 \\\n  couchbase-guru\n```\n\n## Risks associated with LLMs\n\n- The use of large language models and similar technology involves risks, including the potential for inaccurate or harmful outputs.\n- Couchbase does not review or evaluate the quality or accuracy of such outputs, and such outputs may not reflect Couchbase's views.\n- 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.\n\n## Troubleshooting\n\n- 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.\n- If a search times out, the documentation backend may be busy — retry in a moment.\n- To rule out the public backend, run against your own agent with `--agent-base-url`.\n- If running from source after updating the repo, run `uv sync` to refresh dependencies.\n- Check your MCP client's logs (locations above) for errors.\n\n## Testing\n\nUnit tests run offline (the backend is mocked):\n\n```bash\nuv sync --extra dev\nuv run pytest tests/\n```\n\nIntegration tests exercise the tool end-to-end against a live agent backend and are opt-in:\n\n```bash\nCB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py\n```\n\nBy default they use the public agent; set `CB_AGENT_BASE_URL` to target a different backend.\n\n---\n\n## 👩‍💻 Contributing\n\nContributions are welcome! To report a bug, request a feature, or contribute improvements, [open a GitHub issue](https://github.com/Couchbase-Ecosystem/couchbase-guru/issues).\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for developer setup (environment with `uv`, linting/formatting with Ruff, pre-commit hooks, and project structure).\n\n```bash\n# Clone and set up\ngit clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git\ncd couchbase-guru\n\n# Install with development dependencies\nuv sync --extra dev\n\n# Install pre-commit hooks\nuv run pre-commit install\n```\n\n---\n\n## 📢 Support Policy\n\nWe 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.\n",
  "bytes": 10372,
  "sha": "c8178978ba188887f8828b639e72152d60dd631b0208461aec0c577b5bdcb743",
  "repo_slug": "couchbase-ecosystem/couchbase-guru",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_couchbase_ecosystem_couchbase__10cc58d2/readme"
}