Couchbase MCP Server

What is Couchbase MCP Server?

Couchbase MCP Server is a self-hosted MCP server that allows AI agents to connect to and interact with data in Couchbase clusters, whether hosted on Capella or self-managed. It provides tools across categories including Cluster Health, Data Schema, Key-Value, Query, and Performance, with safety controls via read-only mode and fine-grained tool disabling.

How to use Couchbase MCP Server?

Install the server via PyPI (uvx couchbase-mcp-server) or Docker, or run from source. Configure it in an MCP client (e.g., Claude Desktop) by providing connection details (connection string, credentials or mTLS certificates) in the client’s mcpServers JSON. The server supports both STDIO and Streamable HTTP transports.

Key features of Couchbase MCP Server

• Self-hosted; connects to Capella or self-managed Couchbase clusters
• Tools: cluster health, schema discovery, KV operations, SQL++ queries
• Performance analysis tools for query optimization
• Read-only mode and per-tool disabling for safety control
• Supports basic authentication and mTLS for secure connections
• Distributed as PyPI package and Docker image

Use cases of Couchbase MCP Server

• AI agents querying and managing documents in Couchbase buckets
• Automated schema discovery for analytics or data cataloging
• Performance monitoring and query optimization via SQL++ tools
• Integrating Couchbase data into MCP-enabled LLM workflows

FAQ from Couchbase MCP Server

What are the prerequisites to run the server?

Python 3.10+, a running Couchbase cluster (Capella free tier works), uv installed, and an MCP client like Claude Desktop.

How do I authenticate the server to a Couchbase cluster?

Either provide username/password (CB_USERNAME, CB_PASSWORD) or use mTLS client certificate and key (CB_CLIENT_CERT_PATH, CB_CLIENT_KEY_PATH). The connection string is always required.

What is read-only mode?

When the environment variable CB_MCP_READ_ONLY_MODE is set to true, all KV write tools are disabled and SQL++ queries that modify data are blocked. This is the default setting.

Can I disable specific tools?

Yes, you can fine‑tune which tools are available by disabling individual tools through server configuration.

How is the server distributed and supported?

It is available as a PyPI package and via Docker. Enterprise support is available through licensing Couchbase AI Data Plane.