How to add Couchbase MCP Server to Windsurf
Let LLMs query Couchbase clusters, run SQL++, manage documents, and analyze query performance. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.
Last updated June 14, 2026 · 32★ · stdio · apikey
Windsurf config for Couchbase MCP Server
uvx couchbase-mcp-server{
"mcpServers": {
"couchbase-mcp-server": {
"command": "uvx",
"args": [
"couchbase-mcp-server"
],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Setup steps
- 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
- 2Paste the Couchbase MCP Server config below.
- 3Fill in placeholder secrets, then save.
- 4Click Refresh in the MCP panel.
- 5Couchbase MCP Server's tools become available to Cascade.
Before you start
- Python 3.10 or higher
- A running Couchbase cluster (e.g. Capella free tier or self-hosted Couchbase Server)
- uv installed to run the server
- An MCP client such as Claude Desktop, Cursor, Windsurf, VS Code, or JetBrains IDEs
- Couchbase credentials: username/password (basic auth) or client certificate and key (mTLS)
What Couchbase MCP Server can do in Windsurf
get_server_configuration_statusGet the status of the MCP server.
test_cluster_connectionCheck the cluster credentials by connecting to the cluster.
get_cluster_health_and_servicesGet cluster health status and list of all running services.
get_buckets_in_clusterGet a list of all the buckets in the cluster.
get_scopes_in_bucketGet a list of all the scopes in the specified bucket.
get_collections_in_scopeGet a list of all the collections in a specified scope and bucket. Requires the cluster to have the Query service.
get_scopes_and_collections_in_bucketGet a list of all the scopes and collections in the specified bucket.
get_schema_for_collectionGet the structure for a collection.
Security
CB_MCP_READ_ONLY_MODE defaults to true, disabling all KV and SQL++ write operations. Disabling individual tools does not by itself prevent data modification (e.g. SQL++ DML via run_sql_plus_plus_query); the Couchbase user's RBAC permissions are the authoritative security control and should be scoped appropriately. Streamable HTTP and SSE transport modes do not include authorization support.
Couchbase MCP Server + Windsurf FAQ
Where is the Windsurf config file?
Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Couchbase MCP Server config there under the "mcpServers" key and restart the client.
Is Couchbase MCP Server safe to use with Windsurf?
CB_MCP_READ_ONLY_MODE defaults to true, disabling all KV and SQL++ write operations. Disabling individual tools does not by itself prevent data modification (e.g. SQL++ DML via run_sql_plus_plus_query); the Couchbase user's RBAC permissions are the authoritative security control and should be scoped appropriately. Streamable HTTP and SSE transport modes do not include authorization support.
Is it safe to let an LLM modify my data?
By default CB_MCP_READ_ONLY_MODE is true, which disables all KV and SQL++ write operations. To allow writes, set it to false. Note that the Couchbase user's RBAC permissions are the authoritative security control, so scope your credentials appropriately.
How do I authenticate?
You can use basic authentication with CB_CONNECTION_STRING, CB_USERNAME, and CB_PASSWORD, or mTLS using CB_CLIENT_CERT_PATH and CB_CLIENT_KEY_PATH. If both are provided, the client certificate is used.
Which transports are supported?
stdio (default), Streamable HTTP, and SSE (deprecated). HTTP and SSE modes do not include authorization support. Set the mode via CB_MCP_TRANSPORT or --transport.