Mcp Server Couchbase

Couchbase MCP Server

Couchbase MCP Server is a self-hosted Model Context Protocol (MCP) server that connects AI agents and LLM-powered assistants — Claude, Cursor, Windsurf, VS Code Copilot, and other MCP clients — to data in Couchbase clusters, whether hosted on Capella or self-managed. MCP is an open standard for letting AI assistants call tools and query external data sources; this server implements that standard for Couchbase, so an AI agent can inspect your cluster, run SQL++ queries, read and write documents, and analyze query performance using natural language instead of hand-written code.

It provides tools across categories including Cluster Health, Data Schema, Key-Value, Query, and Performance — with safety controls via read-only mode (on by default) and fine-grained tool disabling, so you can let an AI agent explore and query your data without risking unintended writes. It supports both STDIO and Streamable HTTP transports.

Couchbase MCP server is distributed as a Python Package Index (PyPI) package and via Docker. Enterprise support for Couchbase MCP Server is available by licensing Couchbase AI Data Plane, which also entitles use and enterprise support of Couchbase Agent Memory and Couchbase Agent Catalog.

For full documentation, visit mcp-server.couchbase.com.

For full documentation, visit docs.couchbase.com/mcp-server.

Table of Contents

• Why Couchbase MCP Server
• Example Prompts
• Features/Tools
• Prerequisites
• Configuration
• Operational Insights Server
• Streamable HTTP Transport Mode
• SSE Transport Mode
• OAuth 2.1 Authorization
• Docker Image
• Usage Data Collection
• Troubleshooting Tips
• Integration Testing
• FAQ
• Contributing
• Support Policy

Why Couchbase MCP Server

• Safe by default — write operations (document upserts/inserts/deletes and data-modifying SQL++ queries) are blocked unless you explicitly set CB_MCP_READ_ONLY_MODE=false, and individual tools can be disabled or gated behind user confirmation.
• Works with Capella and self-managed clusters — the same configuration connects to Couchbase Capella (fully managed) or a self-hosted Couchbase Server cluster.
• RBAC-aware — tool disabling is a convenience layer for guiding LLM behavior; the underlying Couchbase user's role-based access control remains the authoritative security boundary.
• Production transports — run over STDIO for local desktop clients, or Streamable HTTP with optional OAuth 2.1 (JWT/JWKS, provider-agnostic — Auth0, Okta, Keycloak, Entra, Cognito, etc.) for shared/remote deployments.
• Any MCP client — tested with Claude Desktop, Cursor, Windsurf, VS Code, and JetBrains AI Assistant/Junie; works with any client implementing the MCP specification.

Example Prompts

Once the server is connected, you can talk to your Couchbase cluster in natural language through your AI assistant. For example:

• "What buckets, scopes, and collections do I have in this cluster, and what's the schema of the orders collection?"
• "Run a SQL++ query to find the 10 most recent documents in the users collection where status = 'active'."
• "What are the 5 slowest queries on this cluster in the last hour, and are any of them missing a covering index?"
• "Check whether this cluster is healthy and tell me which services are running."
• "Insert a new document into the products collection with these fields: ..." (requires CB_MCP_READ_ONLY_MODE=false)

Features/Tools

This distribution ships two servers: the operational server (default — the tables immediately below) talks to a regular Couchbase cluster via the couchbase SDK, and the Operational Insights server (its own table further down) talks to Operational Insights clusters via the couchbase-operational-insights SDK.

Cluster setup & health tools

Data model & schema discovery tools

Document KV operations tools

Query and indexing tools

Full-text search (FTS) tools

Requires Couchbase Server 7.6+ and the Search service. Vector search is not supported by these tools (see the separate vector search tooling).

Query performance analysis tools

Operational Insights tools

Registered by the separate operational-insights server (see Operational Insights Server below), not the default operational one.

The Server Async Request API tools form a start → poll → discard-or-cancel flow for long-running queries: run_query_async returns a query_handle, get_async_query_results is polled until it reports readiness (and returns the rows), then either discard_async_query_results frees the results or, for a query still running, cancel_async_query stops it.

Note: get_collections_in_scope, get_schema_for_collection, create_index and list_indexes exist, with different behavior, on both servers. (get_server_configuration_status also appears on both, but it is deliberately one shared tool — same implementation, same result shape — so it needs no disambiguation.) Each server is a separate process, so this is only a concern if a single MCP client registers both operational and operational-insights simultaneously — in that case, disambiguate at the client configuration layer (e.g. by giving the two server entries distinct names in the client's own config).

Prerequisites

• Python 3.10 or higher.
• A running Couchbase cluster. The easiest way to get started is to use Capella free tier, which is fully managed version of Couchbase server. You can follow instructions to import one of the sample datasets or import your own.
• uv installed to run the server.
• An MCP client such as Claude Desktop installed to connect the server to Claude. The instructions are provided for Claude Desktop and Cursor. Other MCP clients could be used as well.

Configuration

The MCP server can be run either from the prebuilt PyPI package or the source using uv.

Running from PyPI

We publish a pre built PyPI package for the MCP server.

Server Configuration using Pre built Package for MCP Clients

Basic Authentication

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

or

mTLS

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

Note: If you have other MCP servers in use in the client, you can add it to the existing mcpServers object.

Running from Source

The MCP server can be run from the source using this repository.

Clone the repository to your local machine

git clone https://github.com/couchbase/mcp-server-couchbase.git

Server Configuration using Source for MCP Clients

This is the common configuration for the MCP clients such as Claude Desktop, Cursor, Windsurf Editor.

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

Note: path/to/cloned/repo/mcp-server-couchbase/ should be the path to the cloned repository on your local machine. Don't forget the trailing slash at the end!

Note: If you have other MCP servers in use in the client, you can add it to the existing mcpServers object.

Additional Configuration for MCP Server

The server can be configured using environment variables or command line arguments:

Read-Only Mode Configuration

CB_MCP_READ_ONLY_MODE is the single switch controlling write operations:

• When true (default): All write operations (KV, Query, scope/collection management, index management, and FTS index management) are disabled. All write tools (KV: upsert, insert, replace, delete, sub-document mutate; scope/collection management: create_scope, create_collection, delete_scope, delete_collection; index management: create_index, build_index, drop_index; FTS index management: upsert_fts_index, drop_fts_index) are not loaded and will not be available to the LLM, and SQL++ queries that modify data or structure are blocked.
• When false: All write tools are loaded and SQL++ data/structure modification queries are allowed.

This is the recommended safe default to prevent inadvertent data modifications by LLMs.

Note: For authentication, you need either the Username and Password or the Client Certificate and key paths. Optionally, you can specify the CA root certificate path that will be used to validate the server certificates. If both the Client Certificate & key path and the username and password are specified, the client certificates will be used for authentication.

Disabling Tools

You can disable specific tools to prevent them from being loaded and exposed to the MCP client. Disabled tools will not appear in the tool discovery and cannot be invoked by the LLM.

Supported Formats

Comma-separated list:

# Environment variable
CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"

# Command line
uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id

File path (one tool name per line):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

# Command line
uvx couchbase-mcp-server --disabled-tools disabled_tools.txt

File format (e.g., disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Lines starting with # are treated as comments and ignored.

MCP Client Configuration Examples

Using comma-separated list:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"
      }
    }
  }
}

Using file path (recommended for many tools):

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"
      }
    }
  }
}

Important Security Note

Warning: Disabling tools alone does not guarantee that certain operations cannot be performed. The underlying database user's RBAC (Role-Based Access Control) permissions are the authoritative security control.

For example, even if you disable upsert_document_by_id and delete_document_by_id, data modifications can still occur via the run_sql_plus_plus_query tool using SQL++ DML statements (INSERT, UPDATE, DELETE, MERGE) unless:

• The CB_MCP_READ_ONLY_MODE is set to true (default), OR
• The database user lacks the necessary RBAC permissions for data modification

Best Practice: Always configure appropriate RBAC permissions on your Couchbase user credentials as the primary security measure. Use tool disabling as an additional layer to guide LLM behavior and reduce the attack surface, not as the sole security control.

Elicitation/Confirmation for Tool Calls

You can require explicit user confirmation for specific tools before execution (when the MCP client supports elicitation).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools supports these formats:

• Comma-separated list
• File path (one tool name per line, # comments supported)

Example:

# Environment variable
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

# Command line
uvx couchbase-mcp-server --confirmation-required-tools delete_document_by_id,replace_document_by_id

When a listed tool is invoked:

• If the client supports elicitation, the user is prompted to confirm.
• If the client does not support elicitation, the tool executes without confirmation for backward compatibility.

You can also check the version of the server using:

uvx couchbase-mcp-server --version

Logging

The MCP server logs to stderr by default. Logging is configured with the CB_MCP_LOG_* variables listed in Additional Configuration:

• CB_MCP_LOG_LEVEL — how much is logged: info (the default) logs lifecycle events and tool invocations, debug adds verbose internal detail, and off disables all logging.
• CB_MCP_LOG_SINKS — where logs go: stderr (the default), per-level rotating files (file), or both. With file, one file is written per level (for example mcp_server.info.log and mcp_server.error.log) at the path set by CB_MCP_LOG_FILE.
• Rotation size — CB_MCP_LOG_ROTATION_MAX_SIZE_MB is the global size (in MB) at which each per-level file rotates. Override individual levels with CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG), also in MB, which inherit the global when unset. A size of 0 (global or per-level) is invalid and falls back to the default (1 MB) with a startup warning. CB_MCP_LOG_MAX_BYTES (bytes) is deprecated but still honored for backward compatibility; it is ignored when CB_MCP_LOG_ROTATION_MAX_SIZE_MB is also set, and prints a deprecation warning at startup.
• Retention — CB_MCP_LOG_RETENTION_BACKUP_COUNT sets how many rotated backups are kept per level (excluding the live file); the default of 1 preserves the previous behaviour. Override individual levels with CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG), which inherit the global value when unset. Set a count to 0 to keep only the live file for that level — it is still capped by the rotation size (reset on rollover rather than backed up).
• Server-config snapshot — when the file sink is active, a one-shot record (OS, Python, dependency versions, transport, resolved logging config, and redacted server config) is written as JSON to a dedicated mcp_server_config.log.json file (derived from the CB_MCP_LOG_FILE base). It is overwritten on each start, so support always has the current config and it never scrolls out of a rotating log.

# Enable debug logging to both stderr and rotating per-level files
uvx couchbase-mcp-server --log-level=debug --log-sinks=stderr,file

# Keep 30 rotated ERROR backups but only the live DEBUG file
uvx couchbase-mcp-server --log-level=debug --log-sinks=file \
  --log-error-retention-backup-count=30 --log-debug-retention-backup-count=0

For more details, see the documentation.

Client Specific Configuration

Operational Insights Server

Alongside the default operational server (the one every section above describes), this distribution ships a second server for Operational Insights clusters, using the separate couchbase-operational-insights SDK. It is a different product from a regular Couchbase cluster and runs as an independent process on its own port.

Run it by passing operational-insights as the CLI subcommand (or appending it as the container's command):

uvx couchbase-mcp-server operational-insights
# or, from source:
uv run src/mcp_server.py operational-insights
# or, via Docker:
docker run --rm -i \
  -e CB_OI_CONNECTION_STRING=http://localhost:8095 \
  -e CB_OI_USERNAME=Administrator \
  -e CB_OI_PASSWORD=password \
  couchbase/mcp-server:<version> operational-insights

--connection-string is an HTTP(S) URL, not a couchbase:// connection string — e.g. http://localhost:8095 for a local Operational Insights server, or https://<host>:18095 for Capella. This is the single most common misconfiguration when pointing this server at a cluster.

Every other flag (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) is identical to the operational server's — see Additional Configuration for MCP Server — except the defaults for port (8001, not 8000) and log file (mcp_server_operational_insights.log, not mcp_server.log), since two servers cannot share either. OAuth uses the same scope labels (couchbase-mcp:read / couchbase-mcp:write) as the operational server, so an existing IdP configuration works for both without changes.

Example MCP client configuration:

{
  "mcpServers": {
    "couchbase-operational-insights": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OI_CONNECTION_STRING": "http://localhost:8095",
        "CB_OI_USERNAME": "Administrator",
        "CB_OI_PASSWORD": "password"
      }
    }
  }
}

See Operational Insights tools above for the tool list, and the note there about the three tool names shared with the operational server.

Both servers share a single MCP Registry listing, io.github.couchbase/mcp-server-couchbase, published from server.json. The listing has a separate package entry for each server (PyPI and Docker). Each entry passes its subcommand (operational or operational-insights) and declares only that server's arguments and environment variables.

Streamable HTTP Transport Mode

The MCP Server can be run in Streamable HTTP transport mode which allows multiple clients to connect to the same server instance via HTTP. Check if your MCP client supports streamable http transport before attempting to connect to MCP server in this mode.

Note: OAuth 2.1 authorization is supported on this transport. See OAuth 2.1 Authorization. Without OAuth configured, the HTTP endpoint is unauthenticated.

Usage

By default, the MCP server will run on port 8000 but this can be configured using the --port or CB_MCP_PORT environment variable.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=http

The server will be available on http://localhost:8000/mcp. This can be used in MCP clients supporting streamable http transport mode such as Cursor.

MCP Client Configuration

{
  "mcpServers": {
    "couchbase-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

SSE Transport Mode

There is an option to run the MCP server in Server-Sent Events (SSE) transport mode.

Note: SSE mode has been deprecated by MCP. We have support for Streamable HTTP.

SSE: Usage

By default, the MCP server will run on port 8000 but this can be configured using the --port or CB_MCP_PORT environment variable.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=sse

The server will be available on http://localhost:8000/sse. This can be used in MCP clients supporting SSE transport mode such as Cursor.

SSE: MCP Client Configuration

{
  "mcpServers": {
    "couchbase-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

OAuth 2.1 Authorization

When running with --transport=http, the MCP server can act as an OAuth 2.1 resource server: it validates incoming bearer JWTs against your identity provider's JWKS. It is provider-agnostic (any OAuth 2.1 / OIDC provider that publishes a JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, etc.) and does not issue tokens or manage users. OAuth settings are ignored on stdio.

OAuth is configured with the CB_MCP_OAUTH_* variables listed in Additional Configuration:

• OAuth activates only when all three of CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER, and CB_MCP_OAUTH_JWT_AUDIENCE are set; setting only some of them fails at startup.
• Setting CB_MCP_OAUTH_MCP_BASE_URL additionally publishes RFC 9728 Protected Resource Metadata so PRM-aware clients can discover the authorization server.
• Access is gated by two scopes read from the token's scope/scp claim: couchbase-mcp:read (read tools, including SQL++) and couchbase-mcp:write (write tools: KV mutations, scope/collection management, index management, and FTS index management). Full access requires both. If your IdP can't emit those canonical labels, override them with CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http \
  --oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
  --oauth-issuer='https://auth.example.com/' \
  --oauth-audience='couchbase-mcp-server' \
  --oauth-mcp-base-url='<public_base_url_of_this_server>'

For full details, see the documentation.

Docker Image

The MCP server can also be built and run as a Docker container. Prebuilt images can be found on DockerHub or pulled via docker pull docker.io/couchbase/mcp-server:latest.

Alternatively, we are part of the Docker MCP Catalog.

Building Image

docker build -t mcp/couchbase-src .

docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mcp/couchbase-src .

# Build with default image name (mcp/couchbase-src)
./build.sh

# Build with custom image name
./build.sh my-custom/image-name

# View git commit hash in image
docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase-src:latest

# View all metadata labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest

Running

The MCP server can be run with the environment variables being used to configure the Couchbase settings. The environment variables are the same as described in the Additional Configuration section.

Independent Docker Container

docker run --rm -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
  -e CB_MCP_READ_ONLY_MODE='<true|false>' \
  -e CB_MCP_CONFIRMATION_REQUIRED_TOOLS='delete_document_by_id' \
  -e CB_MCP_PORT=9001 \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 9001:9001 \
  mcp/couchbase-src

The CB_MCP_PORT and CB_MCP_HOST environment variables are only applicable in the case of HTTP transport modes like http and sse.

Docker: MCP Client Configuration

The Docker image can be used in stdio transport mode with the following configuration.

{
  "mcpServers": {
    "couchbase-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_user>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "mcp/couchbase-src"
      ]
    }
  }
}

Notes

• The couchbase_connection_string value depends on whether the Couchbase server is running on the same host machine, in another Docker container, or on a remote host. If your Couchbase server is running on your host machine, your connection string would likely be of the form couchbase://host.docker.internal. For details refer to the docker documentation.
• You can specify the container's networking using the --network=<your_network> option. The network you choose depends on your environment; the default is bridge. For details, refer to network drivers in docker.

Risks Associated with LLMs

• The use of large language models and similar technology involves risks, including the potential for inaccurate or harmful outputs.
• Couchbase does not review or evaluate the quality or accuracy of such outputs, and such outputs may not reflect Couchbase's views.
• You are solely responsible for determining whether to use large language models and related technology, and for complying with any license terms, terms of use, and your organization's policies governing your use of the same.

Usage Data Collection

This product automatically collects usage and performance data (such as product name and version) and browser information (such as IP address) (collectively, "Usage Data"). Couchbase uses Usage Data, along with other data you may provide to Couchbase (such as your user name or email address), to develop and improve our products as well as inform our sales and marketing programs. We do not access or collect any data you store in Couchbase products. We use Usage Data to understand aggregate usage patterns and make our products more useful to you. For more information on how Couchbase collects, protects, and processes information, please refer to the Couchbase Privacy Policy viewable at https://www.couchbase.com/privacy-policy.

Troubleshooting Tips

• Ensure the path to your MCP server repository is correct in the configuration if running from source.
• Verify that your Couchbase connection string, database username, password or the path to the certificates are correct.
• If using Couchbase Capella, ensure that the cluster is accessible from the machine where the MCP server is running.
• Check that the database user has proper permissions to access at least one bucket.
• Confirm that the uv package manager is properly installed and accessible. You may need to provide absolute path to uv/uvx in the command field in the configuration.
• Check the logs for any errors or warnings that may indicate issues with the MCP server. The location of the logs depend on your MCP client.
• If you are observing issues running your MCP server from source after updating your local MCP server repository, try running uv sync to update the dependencies.

Integration testing

We provide high-level MCP integration tests to verify that the server exposes the expected tools and that they can be invoked against a demo Couchbase cluster.

1. Export demo cluster credentials:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • Optional: CB_MCP_TEST_BUCKET (a bucket to probe during the tests)
   • Optional, for the Operational Insights server's own tests: CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD. Those tests skip automatically (not fail) when unset.
2. Run the tests:

uv run --extra dev pytest tests/integration -v

FAQ

What is the Couchbase MCP Server? It's a self-hosted implementation of the Model Context Protocol that lets AI assistants and agents (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie, and any other MCP client) query and, optionally, modify data in a Couchbase cluster using natural language.

View the full README on GitHub