Couchbase
A server that enables natural language interactions with Couchbase databases through the Model Context Protocol, allowing users to perform SQL++ queries on Couchbase Capella clusters using conversational commands.
What is Couchbase?
Couchbase is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to server that enables natural language interactions with couchbase databases through the model context protocol, allowing users to perform sql++ queries on couchbase capella clusters using conversationa...
A server that enables natural language interactions with Couchbase databases through the Model Context Protocol, allowing users to perform SQL++ queries on Couchbase Capella clusters using conversational commands.
This server falls under the Databases category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- A server that enables natural language interactions with Cou
Use Cases
Maintainer
Works with
Installation
NPM
npx -y couchbase-mcp-serverPIP
pip install couchbase-mcp-serverManual Installation
npx -y couchbase-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Couchbase
The Couchbase MCP Server enables AI assistants to interact with Couchbase clusters and Couchbase Capella using natural language, translating conversational queries into SQL++ (N1QL) and exposing 30 tools covering cluster health, schema discovery, document CRUD, query execution, index management, and performance analysis. By default the server runs in read-only mode to prevent accidental data modification, and it supports both basic authentication and mTLS certificate-based authentication. It is ideal for data teams who want to explore and query their Couchbase databases conversationally without writing SQL++ by hand.
Prerequisites
- Python 3.10 or later and the uv package manager installed
- A running Couchbase cluster (self-hosted) or a Couchbase Capella account with a cluster endpoint
- Database credentials: CB_USERNAME and CB_PASSWORD, or mTLS certificate and key paths
- An MCP-compatible client such as Claude Desktop, Cursor, or VS Code with MCP support
Install the server from PyPI using uvx
The easiest installation method is uvx, which runs the package directly without a global install. Alternatively, install with pip.
uvx couchbase-mcp-server
# or with pip:
pip install couchbase-mcp-serverGather your Couchbase connection details
You need the cluster connection string (e.g., couchbases://cluster.example.com or couchbases://<cluster-id>.dp.cloud.couchbase.com), your username, and your password. For Capella, find these in the Connect tab of your cluster.
Configure your MCP client with connection credentials
Add the couchbase-mcp-server to your MCP client config with the required environment variables. For Claude Desktop on macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json.
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server"],
"env": {
"CB_CONNECTION_STRING": "couchbases://<your-cluster-endpoint>",
"CB_USERNAME": "<your-username>",
"CB_PASSWORD": "<your-password>",
"CB_MCP_READ_ONLY_MODE": "true"
}
}
}
}Restart your MCP client
Restart Claude Desktop or your chosen MCP client to apply the new configuration and establish the Couchbase connection.
Test the connection and explore your cluster
Ask your AI assistant to list buckets, check cluster health, or run a simple SQL++ query to confirm the server is connected and credentials are valid.
Couchbase Examples
Client configuration
Claude Desktop configuration for the Couchbase MCP server with read-only mode enabled.
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server"],
"env": {
"CB_CONNECTION_STRING": "couchbases://cb.example.cloud.couchbase.com",
"CB_USERNAME": "admin",
"CB_PASSWORD": "<your-password>",
"CB_MCP_READ_ONLY_MODE": "true",
"CB_MCP_TRANSPORT": "stdio"
}
}
}
}Prompts to try
Example prompts for querying and exploring Couchbase clusters through the MCP server.
- "List all buckets in my Couchbase cluster"
- "Check the health and services running on my Couchbase cluster"
- "What collections are in the travel-sample bucket's inventory scope?"
- "Run this SQL++ query: SELECT name, type FROM `travel-sample`.inventory.hotel LIMIT 10"
- "Show me the indexes defined on the travel-sample bucket and suggest which ones are missing"Troubleshooting Couchbase
Connection fails with 'unable to connect to host'
Verify CB_CONNECTION_STRING uses the correct scheme (couchbases:// for TLS, couchbase:// for plain). For Capella, use the connection string from the Connect tab. Ensure your IP is whitelisted in Capella's allowed IP list under Database Access.
Authentication error: invalid username or password
Confirm the credentials belong to a database user (not your Capella login). In Capella, create a database user under Settings → Database Access with appropriate RBAC roles such as Data Reader.
Write operations fail even though CB_MCP_READ_ONLY_MODE is false
The database user's RBAC permissions are the authoritative access control layer. Ensure the user has Data Writer or Admin roles in Couchbase for the target bucket. Read-only mode is an additional guardrail on top of RBAC.
Frequently Asked Questions about Couchbase
What is Couchbase?
Couchbase is a Model Context Protocol (MCP) server that server that enables natural language interactions with couchbase databases through the model context protocol, allowing users to perform sql++ queries on couchbase capella clusters using conversational commands. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Couchbase?
Install via npm with the command: npx -y couchbase-mcp-server. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
Which AI clients work with Couchbase?
Couchbase works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Couchbase free to use?
Yes, Couchbase is open source and available under the Apache-2.0 license. You can use it freely in both personal and commercial projects.
Couchbase Alternatives — Similar Databases Servers
Looking for alternatives to Couchbase? Here are other popular databases servers you can use with Claude, Cursor, and VS Code.
Excelize
★ 20.6kGo language library for reading and writing Microsoft Excel™ (XLAM / XLSM / XLSX / XLTM / XLTX) spreadsheets
MCP Toolbox for Databases
★ 15.3kOpen source MCP server specializing in easy, fast, and secure tools for Databases.
DBHub
★ 2.8kA universal database gateway MCP server that enables AI assistants to connect to and query multiple databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite) with support for schema exploration, SQL execution, and secure connections via SSH tunnels.
Tabularis
★ 2.1kA lightweight, cross-platform database client for developers. Supports MySQL, PostgreSQL and SQLite. Hackable with plugins. Built for speed, security, and aesthetics.
Postgres AI Guide
★ 1.7kMCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.
Anyquery
★ 1.7k🏎️ 🏠 ☁️ - Query more than 40 apps with one binary using SQL. It can also connect to your PostgreSQL, MySQL, or SQLite compatible database. Local-first and private by design.
Browse More Databases MCP Servers
Explore all databases servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Couchbase in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Couchbase?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.