Prerequisites

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

Required

• Python 3.10 or higher - The server requires Python 3.10+ (supports 3.10, 3.11, 3.12, 3.13).

• A running Couchbase cluster - Either:

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

  • A self-hosted Couchbase Server instance

  :::note Compatibility The MCP Server is compatible with Couchbase Server 7.2+ (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.

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