Couchbase-Ecosystem/mcp-server-couchbase
GitHub Repository
Description
Couchbase MCP Server is an implementation that enables unified access to Couchbase clusters, both self-managed and Capella cloud, through the Model Context Protocol (MCP). It allows large language models (LLMs) and agentic applications to interact directly with Couchbase databases for document operations, SQL++ queries, and natural language analysis.
Features
- Unified Couchbase Access: Connects to both Capella (cloud) and self-managed Couchbase clusters.
- Document Operations:
- Get a list of all scopes and collections in a specified bucket
- Retrieve the structure of a collection
- Get a document by ID from a specified scope and collection
- Upsert (insert/update) a document by ID
- Delete a document by ID
- SQL++ Query Support:
- Run SQL++ queries on a specified scope
- Configurable read-only query mode (enabled by default) to restrict queries that modify data or structure
- Natural Language Analysis: Enables LLMs and agentic apps to query and manipulate documents using natural language via MCP clients
- MCP Client Integration: Compatible with clients such as Claude Desktop, Cursor, and Windsurf Editor
- Server-Sent Events (SSE) Transport Mode: Supports SSE for real-time data streaming to clients
- Docker Support: Can be built and deployed as a Docker container with prebuilt images available on DockerHub
- Configurable via Environment Variables: Connection details, authentication, bucket selection, and query mode can all be set via environment variables
- Port Configuration: Default port is 8080, configurable via
FASTMCP_PORT
- Managed Option: Can be used as a managed MCP server in agentic applications via Smithery.ai
Configuration
- Prerequisites:
- Python 3.10+
- Couchbase cluster (Capella or self-managed)
uv installed for running the server- MCP client (e.g., Claude Desktop, Cursor, Windsurf Editor)
- Environment Variables:
CB_CONNECTION_STRING: Couchbase cluster connection stringCB_USERNAME: Username for database accessCB_PASSWORD: Password for the userCB_BUCKET_NAME: Name of the Couchbase bucketREAD_ONLY_QUERY_MODE: Enable/disable mutating SQL++ queries (default: true)MCP_TRANSPORT: Transport mode (e.g., stdio, sse)FASTMCP_PORT: Port for server (default: 8080)
- Docker Deployment: Supports running as a container with the above variables
Usage
- Clone the repository and configure as per your environment
- Integrate with compatible MCP clients for natural language and direct query access
- Optionally deploy as a Docker container
Pricing
No pricing information is provided. This is an open-source project licensed under Apache-2.0.
License
Apache-2.0
mcp couchbase database cloud
