Prerequisites

Before using the Couchbase MCP Server, ensure you have the following:

Required​

• Python 3.10–3.14 - The Couchbase MCP Server aims to support Python versions in security or bug-fix (a.k.a. maintenance) status. Python versions that have reached their End-of-Life date are not supported.

• A running Couchbase cluster - Either:

  • Couchbase Capella (free tier available) - fully managed cloud version

  • A self-hosted Couchbase Server instance

  Compatibility

  The MCP Server is compatible with Couchbase Server 7.6+ (Operational Cluster). The following services are not supported: Couchbase Analytics, Sync Gateway, Couchbase Lite, and Capella AI Services.

• uv or Docker - uv is the recommended way to run the server. Docker is an alternative if you prefer containerized deployments.

• An MCP client - Such as Claude Desktop, Cursor, VS Code, Windsurf, or any MCP-compatible client.

Setup Couchbase Server​

If you don't already have a Couchbase cluster, you can set one up using either option:

• Couchbase Capella (recommended) - Create a free-tier account for a fully managed cloud deployment.

• Self-Managed Couchbase Server - Install Couchbase Server on your own infrastructure.

Getting Sample Data (Optional)​

• Couchbase Capella - Import sample datasets like travel-sample or import your own data.

• Self-Managed Couchbase Server - Install sample buckets like travel-sample from the Couchbase Web Console.

Setup Authentication​

Configure your Couchbase cluster with one of the following authentication methods:

• Basic Authentication: A username and password with access to the required buckets.

• mTLS Authentication: A client certificate and key for mutual TLS authentication.

For Basic Authentication setup, see Manage Database Credentials (Capella) or Manage Users and Roles (self-managed).

For mTLS setup, see Configure Client Certificate Authentication.

Ensure that:

• The cluster is accessible from the machine running the MCP server.

• If using Capella, the machine's IP address is allowed.

  This is only required when the MCP server reaches Capella over the public internet. If you host the MCP server in a VPC or on a network privately connected to Capella, IP allow-listing is not needed. Connectivity between the MCP server and Capella follows the same rules as any Couchbase SDK client.

• The database user has proper permissions to access at least one bucket.