Couchbase MCP server
Couchbase's MCP server lets an agent explore buckets, scopes, and collections, run SQL++ queries, and do key-value document operations.
The Couchbase MCP server, maintained under the Couchbase Ecosystem organization, connects an AI agent to data in a Couchbase cluster. The agent can map the data model end to end — list buckets, scopes, and collections and read a collection's structure — then work with documents through direct key-value operations (get, insert, upsert, replace, delete by ID) and run analytical SQL++ (N1QL) queries against a scope. It also exposes the query toolbox: list indexes, get Index Advisor recommendations for a SQL++ statement, and generate or evaluate an EXPLAIN plan, plus a suite of performance-analysis tools that surface the longest-running and most-frequent queries, the largest response sizes and result counts, and queries that use a primary index, miss a covering index, or are not selective. Connection-health tools round it out so the agent can verify credentials and inspect running services.
It is published to PyPI as couchbase-mcp-server and runs locally over stdio, launched with uvx (uvx couchbase-mcp-server) or via Docker, authenticating with CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD (mTLS is also supported). It works against Couchbase Server and Capella. A read-only mode is the default — CB_MCP_READ_ONLY_MODE is true unless you change it, which simply does not load the KV write tools — so handing a cluster to an agent for exploration carries no write risk out of the box. The project is Couchbase community-maintained and is not covered by official Couchbase support.
Quick install
Copy-paste configs are provided for all 8 supported clients. Pick your client below.
Add to ~/.claude.json
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": [
"couchbase-mcp-server"
],
"env": {
"CB_CONNECTION_STRING": "<CB_CONNECTION_STRING>",
"CB_USERNAME": "<CB_USERNAME>",
"CB_PASSWORD": "<CB_PASSWORD>"
}
}
}
}claude mcp add couchbase -- uvx couchbase-mcp-serverAvailable tools
| Tool | Description |
|---|---|
| get_server_configuration_status | Gets the status of the MCP server. |
| test_cluster_connection | Checks the cluster credentials by connecting to the cluster. |
| get_cluster_health_and_services | Gets cluster health status and the list of running services. |
| get_buckets_in_cluster | Lists all buckets in the cluster. |
| get_scopes_in_bucket | Lists all scopes in a specified bucket. |
| get_collections_in_scope | Lists all collections in a specified scope and bucket. |
| get_scopes_and_collections_in_bucket | Lists all scopes and collections in a specified bucket. |
| get_schema_for_collection | Gets the inferred structure of a collection. |
| get_document_by_id | Gets a document by ID from a specified scope and collection. |
| upsert_document_by_id | Upserts a document by ID into a specified scope and collection. |
| insert_document_by_id | Inserts a new document by ID; fails if the document already exists. |
| replace_document_by_id | Replaces an existing document by ID; fails if it does not exist. |
| delete_document_by_id | Deletes a document by ID from a specified scope and collection. |
| list_indexes | Lists all indexes in the cluster with their definitions. |
| get_index_advisor_recommendations | Gets Index Advisor recommendations for a given SQL++ query. |
| run_sql_plus_plus_query | Runs a SQL++ (N1QL) query on a specified scope. |
| explain_sql_plus_plus_query | Generates and evaluates an EXPLAIN plan for a SQL++ query. |
| get_longest_running_queries | Gets the longest-running queries by average service time. |
| get_most_frequent_queries | Gets the most frequently executed queries. |
| get_queries_with_largest_response_sizes | Gets the queries with the largest response sizes. |
| get_queries_with_large_result_count | Gets the queries with the largest result counts. |
| get_queries_using_primary_index | Gets queries that use a primary index. |
| get_queries_not_using_covering_index | Gets queries that do not use a covering index. |
| get_queries_not_selective | Gets queries that are not selective. |
Required configuration
- CB_CONNECTION_STRINGRequired
Connection string to the Couchbase cluster.
- CB_USERNAMERequired
Couchbase database username (or use mTLS cert/key paths).
- CB_PASSWORDRequired
Password for the Couchbase user.
- CB_CA_CERT_PATHOptional
Path to a CA certificate for TLS verification. Optional.
- CB_MCP_READ_ONLY_MODEOptional
When true (the default), KV write tools are not loaded. Set to false to enable writes.
What you can do with it
Explore a cluster read-only
In the default read-only mode the agent maps buckets, scopes, and collections, infers schema, and runs SQL++ queries to answer questions — with no document-write tools loaded, so there is no write risk.
Diagnose slow queries
Use the performance tools to surface the longest-running and most-frequent queries and those missing a covering index, then get Index Advisor recommendations and an EXPLAIN plan to guide a fix.
FAQ
- Is it free?
- Yes. The server is open source and free to run; you only pay for the Couchbase Server or Capella cluster it connects to.
- Does it support remote/OAuth?
- No. It runs locally over stdio (via uvx or Docker) and authenticates to the cluster with a connection string plus username/password, or mTLS client certificates. There is no hosted OAuth endpoint.
- Is it official, and can the agent modify data?
- It lives under the Couchbase Ecosystem organization but is community-maintained and not covered by official Couchbase support. Writes are off by default: CB_MCP_READ_ONLY_MODE is true unless you set it to false, which keeps the key-value write tools out of the agent's reach.