couchbase/mcp-server-couchbase

Couchbase MCP Server is a self-hosted Model Context Protocol (MCP) server that connects AI agents and LLM-powered assistants — Claude, Cursor, Windsurf, VS Code Copilot, and other MCP clients — to data in Couchbase clusters, whether hosted on Capella or self-managed. MCP is an open standard for letting AI assistants call tools and query external data sources; this server implements that standard for Couchbase, so an AI agent can inspect your cluster, run SQL++ queries, read and write documents, and analyze query performance using natural language instead of hand-written code.
It provides tools across categories including Cluster Health, Data Schema, Key-Value, Query, and Performance — with safety controls via read-only mode (on by default) and fine-grained tool disabling, so you can let an AI agent explore and query your data without risking unintended writes. It supports both STDIO and Streamable HTTP transports.
Couchbase MCP server is distributed as a Python Package Index (PyPI) package and via Docker. Enterprise support for Couchbase MCP Server is available by licensing Couchbase AI Data Plane, which also entitles use and enterprise support of Couchbase Agent Memory and Couchbase Agent Catalog.
For full documentation, visit mcp-server.couchbase.com.
[ ][cursor-install-basic]
For full documentation, visit docs.couchbase.com/mcp-server.
Table of Contents
- Why Couchbase MCP Server
- Example Prompts
- Features/Tools
- Prerequisites
- Configuration
- Operational Insights Server
- Streamable HTTP Transport Mode
- SSE Transport Mode
- OAuth 2.1 Authorization
- Docker Image
- Usage Data Collection
- Troubleshooting Tips
- Integration Testing
- FAQ
- Contributing
- Support Policy
Why Couchbase MCP Server
- **Safe by default** — write operations (document upserts/inserts/deletes and data-modifying SQL++ queries) are blocked unless you explicitly set CB_MCP_READ_ONLY_MODE=false, and individual tools can be disabled or gated behind user confirmation.
- **Works with Capella and self-managed clusters** — the same configuration connects to Couchbase Capella (fully managed) or a self-hosted Couchbase Server cluster.
- **RBAC-aware** — tool disabling is a convenience layer for guiding LLM behavior; the underlying Couchbase user's role-based access control remains the authoritative security boundary.
- **Production transports** — run over STDIO for local desktop clients, or Streamable HTTP with optional OAuth 2.1 (JWT/JWKS, provider-agnostic — Auth0, Okta, Keycloak, Entra, Cognito, etc.) for shared/remote deployments.
- **Any MCP client** — tested with Claude Desktop, Cursor, Windsurf, VS Code, and JetBrains AI Assistant/Junie; works with any client implementing the MCP specification.
Example Prompts
Once the server is connected, you can talk to your Couchbase cluster in natural language through your AI assistant. For example:
- "What buckets, scopes, and collections do I have in this cluster, and what's the schema of the orders collection?"
- "Run a SQL++ query to find the 10 most recent documents in the users collection where status = 'active'."
- "What are the 5 slowest queries on this cluster in the last hour, and are any of them missing a covering index?"
- "Check whether this cluster is healthy and tell me which services are running."
- "Insert a new document into the products collection with these fields: ..." (requires CB_MCP_READ_ONLY_MODE=false)
Features/Tools
This distribution ships two servers: the **operational** server (default —
the tables immediately below) talks to a regular Couchbase cluster via the
couchbase SDK, and the **Operational Insights**
server (its own table further down) talks to Operational Insights clusters via
the couchbase-operational-insights SDK.
Cluster setup & health tools
| Tool Name | Description |
| --------- | ----------- |
| get_server_configuration_status | Get the server status and configuration without connecting to the cluster — reports read-only mode, disabled/confirmation-required tools, OAuth settings, and the resolved logging configuration |
| test_cluster_connection | Check the cluster credentials by connecting to the cluster |
| get_cluster_health_and_services | Get cluster health status and list of all running services, optionally filtered to specific services via service_types |
| get_client_connectivity_report | Get the SDK's cached connection diagnostics — whether connections were already broken and for how long, without any active network probing |
| get_cluster_metrics | Get one or more cluster statistics over a historic time window via the Management REST API's stats-range endpoint. **Self-managed Couchbase Server 7.6+ only — not available on Capella.** |