Couchbase Model Context Protocol Server to interact with Couchbase clusters
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
Manual Client & Custom JSON ConfigExpand JSON ▾
Client Config & Setup
Choose your client or environment
Target File:
💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.
Documentation Overview
Couchbase MCP Server
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.
[
For full documentation, visit docs.couchbase.com/mcp-server.
Table of Contents
- Why Couchbase MCP Server
- Example Prompts
- Features/Tools
- Prerequisites
- Configuration
- 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
orderscollection?" - "Run a SQL++ query to find the 10 most recent documents in the
userscollectionwhere 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
productscollection with these fields: ..." (requiresCB_MCP_READ_ONLY_MODE=false)
Features/Tools
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_cluster_diagnostics_report | Get the SDK's cached connection diagnostics — whether connections were already broken and for how long, without any active network probing |
Data model & schema discovery tools
| Tool Name | Description |
|---|---|
get_buckets_in_cluster | Get a list of all the buckets in the cluster |
get_scopes_in_bucket | Get a list of all the scopes in the specified bucket |
get_collections_in_scope | Get a list of all the collections in a specified scope and bucket. Note that this tool requires the cluster to have Query service. |
get_scopes_and_collections_in_bucket | Get a list of all the scopes and collections in the specified bucket |
get_schema_for_collection | Get the structure for a collection |
create_scope | Create a new scope in a bucket (Couchbase Server 7.6+ and Capella). Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
create_collection | Create a new collection in an existing scope (Couchbase Server 7.6+ and Capella). Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
delete_scope | Delete a scope and all its collections from a bucket — permanent. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
delete_collection | Delete a collection and all its documents from a scope — permanent. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
Document KV operations tools
Related MCP Servers
Reviews
No reviews yet — be the first to share how this listing worked for you.
Frequently Asked Questions about MCP Server Couchbase
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/mcp-server-couchbase)HTML Embed
<a href="https://allmcps.com/mcp/mcp-server-couchbase"><img src="https://allmcps.com/api/badge/mcp-server-couchbase?style=directory" alt="MCP Server Couchbase on AllMCPs" /></a>Technical Specs & Signals
CategoryDeveloper Tools
27Quality signal: Emerging · 27/100How this signal is calculated ▾
Server availabilityNot measured
Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.
Verified ownership8/20
Documentation & tools11/30
Adoption & activity1/15
Community engagement0/10
A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.
Own this project?
This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.
Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.
Claim & get free dofollowShare & Embed
Add our SVG badge (dark/light directory styles) or embeddable widget to your site.