mcp-server-couchbase — Claude Code MCP server: what it does
Connects an agent to a Couchbase cluster: inspect schemas, run SQL++, read and write documents. Read-only unless you turn writes on.
claude mcp add --env CB_CONNECTION_STRING=<CB_CONNECTION_STRING> --env CB_USERNAME=<CB_USERNAME> --env CB_PASSWORD=<CB_PASSWORD> --env CB_CA_CERT_PATH=<CB_CA_CERT_PATH> --env CB_CLIENT_CERT_PATH=<CB_CLIENT_CERT_PATH> --transport stdio mcp-server-couchbase -- uvx couchbase-mcp-serverWhat mcp-server-couchbase 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.
What it helps with
- 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 for the agent
- What buckets, scopes and collections exist in my Couchbase cluster?
- Run a SQL++ query against the
userscollection and show the first rows - Fetch the document with key
order::1042from theorderscollection
How to install mcp-server-couchbase
Platform CLI
claude mcp add --env CB_CONNECTION_STRING=<CB_CONNECTION_STRING> --env CB_USERNAME=<CB_USERNAME> --env CB_PASSWORD=<CB_PASSWORD> --env CB_CA_CERT_PATH=<CB_CA_CERT_PATH> --env CB_CLIENT_CERT_PATH=<CB_CLIENT_CERT_PATH> --transport stdio mcp-server-couchbase -- uvx couchbase-mcp-serverReplace <…> 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 <command>
Platform CLI
codex mcp add mcp-server-couchbase --env CB_CONNECTION_STRING=<CB_CONNECTION_STRING> --env CB_USERNAME=<CB_USERNAME> --env CB_PASSWORD=<CB_PASSWORD> --env CB_CA_CERT_PATH=<CB_CA_CERT_PATH> --env CB_CLIENT_CERT_PATH=<CB_CLIENT_CERT_PATH> -- uvx couchbase-mcp-serverReplace <…> 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 <command>
Config file
{
"mcpServers": {
"mcp-server-couchbase": {
"command": "uvx",
"args": [
"couchbase-mcp-server"
],
"env": {
"CB_CONNECTION_STRING": "<CB_CONNECTION_STRING>",
"CB_USERNAME": "<CB_USERNAME>",
"CB_PASSWORD": "<CB_PASSWORD>",
"CB_CA_CERT_PATH": "<CB_CA_CERT_PATH>",
"CB_CLIENT_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 <command>
Config file
{
"servers": {
"mcp-server-couchbase": {
"type": "stdio",
"command": "uvx",
"args": [
"couchbase-mcp-server"
],
"env": {
"CB_CONNECTION_STRING": "<CB_CONNECTION_STRING>",
"CB_USERNAME": "<CB_USERNAME>",
"CB_PASSWORD": "<CB_PASSWORD>",
"CB_CA_CERT_PATH": "<CB_CA_CERT_PATH>",
"CB_CLIENT_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 <command>
Platform CLI
gemini mcp add -e CB_CONNECTION_STRING=<CB_CONNECTION_STRING> -e CB_USERNAME=<CB_USERNAME> -e CB_PASSWORD=<CB_PASSWORD> -e CB_CA_CERT_PATH=<CB_CA_CERT_PATH> -e CB_CLIENT_CERT_PATH=<CB_CLIENT_CERT_PATH> mcp-server-couchbase uvx couchbase-mcp-serverReplace <…> 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 <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-server-couchbase
How do I install mcp-server-couchbase in Claude Code?
Run claude mcp add mcp-server-couchbase -e CB_PASSWORD=<CB_PASSWORD> -- uvx couchbase-mcp-server. For certificates and a connection string, use the longer form with --env CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD, CB_CA_CERT_PATH, CB_CLIENT_CERT_PATH and --transport stdio.
What does mcp-server-couchbase do?
It gives an AI agent access to a Couchbase Server or Capella cluster: the agent reads schemas, runs SQL++ and full-text queries, opens documents and checks query and cluster performance.
Can the agent change my data?
Not by default. The server starts read-only and blocks modifying queries. Setting CB_MCP_READ_ONLY_MODE=false enables writes, and the Couchbase user's RBAC still limits what the agent can reach.
