# mcp-server-couchbase Connects an agent to a Couchbase cluster: inspect schemas, run SQL++, read and write documents. Read-only unless you turn writes on. - MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 34 - Author: couchbase - License: Apache-2.0 · policy=link-only · description only; the file stays with the author - Source: https://github.com/couchbase/mcp-server-couchbase - Updated: 2026-10-23 - HTML: https://affpapa.org/en/nevibecode/mcp/mcp-server-couchbase ## What it does The server runs through `uvx` against Capella or a self-managed Couchbase Server cluster. Your agent gets tools to list buckets, scopes and collections, run SQL++ and full-text queries, fetch documents and look into cluster performance. It means you can ask questions about your data from the chat window. Write access is off out of the box. Write tools are not loaded and data-changing queries are rejected until `CB_MCP_READ_ONLY_MODE=false` is set. You can also disable individual tools or put them behind a confirmation step. Roles assigned to the Couchbase user still decide what actually gets through. You need Python 3.10+ and cluster credentials: a connection string, username, password. TLS connections take `CB_CA_CERT_PATH` and `CB_CLIENT_CERT_PATH`. Local clients talk over STDIO; a shared deployment can use Streamable HTTP with OAuth 2.1. ## Requirements - Needs: Python and uv (commands run via uvx) - Environment variables: `CB_CONNECTION_STRING`, `CB_USERNAME`, `CB_PASSWORD`, `CB_CA_CERT_PATH`, `CB_CLIENT_CERT_PATH`, `CB_CLIENT_KEY_PATH`, `CB_MCP_READ_ONLY_MODE`, `CB_MCP_TRANSPORT`, `CB_MCP_HOST`, `CB_MCP_PORT` — keys and tokens: ask the human for the values, never commit them or put them in shared files. ## Install ### Claude Code (native platform) **Platform CLI** ```bash claude mcp add --env CB_CONNECTION_STRING= --env CB_USERNAME= --env CB_PASSWORD= --env CB_CA_CERT_PATH= --env CB_CLIENT_CERT_PATH= --transport stdio mcp-server-couchbase -- uvx couchbase-mcp-server ``` Replace <…> with your own values. 28 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from couchbase-mcp-server ### Codex **Platform CLI** ```bash codex mcp add mcp-server-couchbase --env CB_CONNECTION_STRING= --env CB_USERNAME= --env CB_PASSWORD= --env CB_CA_CERT_PATH= --env CB_CLIENT_CERT_PATH= -- uvx couchbase-mcp-server ``` Replace <…> with your own values. 28 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from couchbase-mcp-server ### Cursor **Config file** File `.cursor/mcp.json`: ```json { "mcpServers": { "mcp-server-couchbase": { "command": "uvx", "args": [ "couchbase-mcp-server" ], "env": { "CB_CONNECTION_STRING": "", "CB_USERNAME": "", "CB_PASSWORD": "", "CB_CA_CERT_PATH": "", "CB_CLIENT_CERT_PATH": "" } } } } ``` Replace <…> with your own values. 28 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from couchbase-mcp-server ### GitHub Copilot **Config file** File `.vscode/mcp.json`: ```json { "servers": { "mcp-server-couchbase": { "type": "stdio", "command": "uvx", "args": [ "couchbase-mcp-server" ], "env": { "CB_CONNECTION_STRING": "", "CB_USERNAME": "", "CB_PASSWORD": "", "CB_CA_CERT_PATH": "", "CB_CLIENT_CERT_PATH": "" } } } } ``` Replace <…> with your own values. 28 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from couchbase-mcp-server ### Gemini CLI **Platform CLI** ```bash gemini mcp add -e CB_CONNECTION_STRING= -e CB_USERNAME= -e CB_PASSWORD= -e CB_CA_CERT_PATH= -e CB_CLIENT_CERT_PATH= mcp-server-couchbase uvx couchbase-mcp-server ``` Replace <…> with your own values. 28 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from couchbase-mcp-server ## When to use it - list buckets, scopes and collections without opening the console - run a SQL++ query from the chat - fetch or update a document by its key - see why a query is slow from cluster metrics - find documents with a full-text search ## Example prompts - What buckets, scopes and collections exist in my Couchbase cluster? - Run a SQL++ query against the `users` collection and show the first rows - Fetch the document with key `order::1042` from the `orders` collection ## Similar - [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408 - [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433 - [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717 - [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409 - [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27669 - [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49845 --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md