Couchbase-Ecosystem/mcp-server-couchbase

Couchbase MCP Server is a self-hosted Model Context Protocol (MCP) server that connects AI agents and assistants — Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant and any other MCP client — to data in Couchbase Server clusters, on Capella or self-managed, and in self-managed Operational Insights clusters. An agent can inspect your cluster, explore schemas, run SQL++, full-text and vector queries, read and write documents, and diagnose query and cluster performance in natural language.

It is read-only by default, supports STDIO and Streamable HTTP (with OAuth 2.1), and is distributed on PyPI and Docker Hub. Enterprise support is available by licensing Couchbase AI Data Plane, which also entitles use and enterprise support of Couchbase Agent Memory and Couchbase Agent Catalog.

Docs License Python 3.10+ PyPI version Install in Cursor Verified on MseeP Trust Score

Full documentation: docs.couchbase.com/mcp-server

Table of Contents

• Why Couchbase MCP Server
• Choosing a Server
• Operational Server
  • Quick Start
  • Connection and Authentication
  • Tools
  • Embedding Providers
  • All Options
• Operational Insights Server
  • Quick Start
  • Connection and Authentication
  • Tools
  • Exporting Large Results
• Common Configuration
  • Safety Controls
  • Transports
  • OAuth 2.1 Authorization
  • Logging
  • Auditing
• Client Setup
• Docker
• Troubleshooting
• FAQ
• Contributing
• Usage Data, LLM Risks and Support Policy

Why Couchbase MCP Server

• Safe by default — write tools are not loaded and data-modifying queries are blocked unless you set CB_MCP_READ_ONLY_MODE=false; individual tools can also be disabled or gated behind user confirmation.
• Couchbase Server and Operational Insights — the operational server connects to Couchbase Capella or a self-managed Couchbase Server cluster with the same configuration; the Operational Insights server connects to self-managed Operational Insights clusters.
• RBAC-aware — tool controls guide the LLM; the Couchbase user's role-based access control remains the authoritative security boundary.
• Production transports — STDIO for local desktop clients, or Streamable HTTP with optional OAuth 2.1 (any JWKS-publishing IdP: Auth0, Okta, Keycloak, Entra, Cognito, …), health checks and audit logging for shared deployments. The operational server can also run multiple workers to use more CPU cores.
• Any MCP client — tested with Claude Desktop, Cursor, Windsurf, VS Code and JetBrains AI Assistant/Junie.

Once connected, you can ask things like:

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

Choosing a Server

This package ships two MCP servers. Each one is started by its own subcommand, connects to a different kind of cluster, and has its own tools. Pick the one that matches your cluster, follow its section for setup and tools, then use Common Configuration for the settings both share. To use both, register each as a separate server in your MCP client.

The subcommand is optional for the operational server today — a bare couchbase-mcp-server starts it — but naming it keeps your configuration unambiguous. Options go after the subcommand: couchbase-mcp-server operational --transport=http. Check the installed version with uvx couchbase-mcp-server --version.

Operational Server

The operational server connects to a Couchbase cluster on Capella or self-managed Couchbase Server, using the couchbase Python SDK.

Operational Quick Start

You need a running Couchbase cluster — the Capella free tier is the quickest way to get one (you can import a sample dataset) — and an MCP client. Add one of these configurations to your client (see Client Setup for where each client keeps it). If the client already has other servers, add couchbase to the existing mcpServers object.

From PyPI with uvx (requires uv and Python 3.10+):

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

With Docker (requires only Docker):

{
  "mcpServers": {
    "couchbase": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_CONNECTION_STRING=couchbases://connection-string",
        "-e", "CB_USERNAME=username",
        "-e", "CB_PASSWORD=password",
        "couchbase/mcp-server:latest", "operational"
      ]
    }
  }
}

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

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

Operational Connection and Authentication

Use either a username and password or a client certificate (mTLS). If both are set, the certificate is used.

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

Operational Tools

Write tools (marked ✏️) are not loaded while read-only mode is on, the default. Tools marked 🖥️ use admin REST endpoints that Capella does not expose: they need self-managed Couchbase Server 7.6+ and are not registered on Capella connections.

Cluster setup and health

Data model and schema discovery

Document (KV) operations

Query and indexing

Full-text search (FTS)

Requires Couchbase Server 7.6+ and the Search service. Scope-level and cluster-level (legacy) indexes are both supported: pass bucket_name and scope_name together for scope-level, or omit both.

Vector search

Both tools embed plain query text with the model configured under Embedding Providers. Available on self-managed Couchbase Server and Capella.

Query performance analysis

Query service health 🖥️

These call the Query service's own admin REST API on every query node.

Tools disabled automatically on Capella

The 🖥️ tools reach Couchbase through admin REST endpoints that Capella does not expose. When every host in CB_CONNECTION_STRING ends in .cloud.couchbase.com, the server does not register them and reports them alongside your own disabled tools in get_server_configuration_status and the startup log. SDK-based tools such as get_cluster_health_and_services and get_client_connectivity_report stay available.

Embedding Providers

run_vector_query and run_vector_search embed query text with the provider set in CB_MCP_EMBEDDING_MODEL_PROVIDER. This is optional: without it the server starts normally and both tools stay registered, but calling them returns an error explaining what to set.

"env": {
  "CB_CONNECTION_STRING": "couchbases://connection-string",
  "CB_USERNAME": "username",
  "CB_PASSWORD": "password",
  "CB_MCP_EMBEDDING_MODEL_PROVIDER": "openai",
  "CB_MCP_EMBEDDING_MODEL": "text-embedding-3-small",
  "CB_MCP_EMBEDDING_MODEL_API_KEY": "sk-..."
}

All Options

Operational Insights Server

The operational-insights server connects to self-managed Operational Insights clusters. Operational Insights is a real-time analytical database (RT-OLAP) for real-time apps and operational intelligence. The server is not available for Capella. It uses the couchbase-operational-insights SDK. It runs as its own process, separate from the operational server.

[!IMPORTANT] CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING is an HTTP(S) URL, not a couchbase:// connection string — e.g. http://localhost:8095, or https://<host>:18095 over TLS. This is the most common misconfiguration.

Operational Insights Quick Start

From PyPI with uvx:

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

With Docker:

{
  "mcpServers": {
    "couchbase-operational-insights": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING=http://host.docker.internal:8095",
        "-e", "CB_OPERATIONAL_INSIGHTS_USERNAME=Administrator",
        "-e", "CB_OPERATIONAL_INSIGHTS_PASSWORD=password",
        "couchbase/mcp-server:latest", "operational-insights"
      ]
    }
  }
}

From source, use the operational source configuration with operational-insights as the last argument and the variables above.

Operational Insights Connection and Authentication

All common configuration applies, with these differences from the operational server:

• The default port is 8001 and the default log file is mcp_server_operational_insights.log, so both servers can run side by side.
• Only one worker is supported (CB_MCP_WORKERS=1), because async query handles live in process memory.
• It has no CB_MCP_EMBEDDING_MODEL_* options.

Operational Insights Tools

All names except get_server_configuration_status are prefixed operational_insights_, so both servers can be registered in one client without collisions. The write tool (marked ✏️) is not loaded while read-only mode is on, the default.

Async queries follow a start → poll → discard-or-cancel flow: operational_insights_run_query_async returns a query_handle, operational_insights_get_async_query_results is polled until ready, then operational_insights_discard_async_query_results frees the results, or operational_insights_cancel_async_query stops a query still running.

Exporting large results

Instead of returning rows, operational_insights_run_query_sync and operational_insights_run_query_async can wrap the statement in COPY ... TO and write the rows to external object storage. Pass all three of copy_to_link (an existing link created with CREATE LINK ... TYPE S3), copy_to_bucket and copy_to_path, plus optionally copy_to_format (json, the default, or parquet). The tool then returns a confirmation with no rows:

{
  "success": true,
  "exported": true,
  "destination": {"link": "s3Link", "bucket": "my-exports", "path": "exports/run1", "format": "json"},
  "message": "Results were written to my-exports/exports/run1 as json. ..."
}

• A partial destination is rejected rather than silently returning rows.
• The sync tool waits for the whole upload; prefer the async tool for large exports.
• Exports are blocked in read-only mode (they write to external storage), so they need CB_MCP_READ_ONLY_MODE=false or a token with couchbase-mcp:write.
• csv is not offered, because it needs an explicit output schema that can't be inferred from an arbitrary SELECT.

Common Configuration

These settings work the same way for both servers. Every option can be set as an environment variable or as a CLI flag after the subcommand.

Safety Controls

Three layers, from broadest to narrowest. Use them together — but remember that none of them replaces RBAC.

[!IMPORTANT] The database user's RBAC permissions are the authoritative security control. For example, disabling upsert_document_by_id and delete_document_by_id does not stop run_sql_plus_plus_query from running INSERT/UPDATE/DELETE/MERGE — only read-only mode or missing RBAC permissions do. Give the server's database user only the permissions it needs.

Read-only mode

CB_MCP_READ_ONLY_MODE (default true) is the single switch for writes:

• true — the write tools marked ✏️ in each server's tool list are not loaded, and queries that modify data or structure are blocked.
• false — write tools are loaded and modifying queries are allowed.

Disabling tools

CB_MCP_DISABLED_TOOLS removes tools from discovery entirely. It accepts a comma-separated list or a path to a file with one tool name per line (# starts a comment):

CB_MCP_DISABLED_TOOLS="upsert_document_by_id,delete_document_by_id"
# or
CB_MCP_DISABLED_TOOLS=/path/to/disabled_tools.txt

# disabled_tools.txt
# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

On Capella, the operational server also disables some admin tools automatically.

Requiring confirmation (elicitation)

CB_MCP_CONFIRMATION_REQUIRED_TOOLS asks the user to confirm before a listed tool runs, using MCP elicitation. It takes the same comma-separated or file formats as disabled tools:

CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

• If the client supports elicitation, the user is prompted before the tool runs.
• If it doesn't, the tool runs without confirmation, for backward compatibility.
• Confirmation needs an MCP session, so it cannot be combined with stateless HTTP (CB_MCP_STATELESS_HTTP=true or CB_MCP_WORKERS above 1). The server refuses to start with that combination.

Transports

Set the transport with CB_MCP_TRANSPORT, the bind address with CB_MCP_HOST (default 127.0.0.1) and the port with CB_MCP_PORT (each server's default port when unset). Without OAuth, the HTTP endpoint is unauthenticated.

uvx couchbase-mcp-server operational \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http

Then point your client at the URL:

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

Multiple workers

One process uses at most about one CPU core. --workers N (CB_MCP_WORKERS) runs N processes behind the same host and port; the number of available cores is a good starting point. Workers are supported by the operational server only. With more than one worker:

• The http transport is required, and the server runs in stateless HTTP mode, because a client's requests can reach different workers. You can also set --stateless-http=true on a single worker, for example behind a load balancer without sticky sessions.
• Confirmation-required tools cannot be used.
• Each process writes its own log files, named with host and process id (mcp_server.<host>.<pid>.info.log) — one set for the supervisor and one per worker.

Health check

In HTTP mode, GET /health returns {"status": "ok", "server": "<server>"} on the MCP port. It is a liveness check: it does not connect to the cluster (so a cluster outage doesn't restart healthy containers), needs no authentication even with OAuth enabled, and is served by every worker. See Docker for probe examples.

OAuth 2.1 Authorization

With --transport=http, either server can act as an OAuth 2.1 resource server, validating bearer JWTs against your identity provider's JWKS. It works with any OAuth 2.1/OIDC provider that publishes a JWKS, and does not issue tokens or manage users. OAuth settings are ignored on stdio.

• OAuth turns on 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 fails at startup.
• CB_MCP_OAUTH_MCP_BASE_URL additionally publishes RFC 9728 Protected Resource Metadata so clients can discover the authorization server.
• Access is gated by two scopes in the token's scope/scp claim: couchbase-mcp:read (read tools) and couchbase-mcp:write (write tools). Full access needs both. Rename them with CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL if your IdP can't emit these labels. Both servers use the same labels, so one IdP configuration covers both.

uvx couchbase-mcp-server operational \
  --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>'

See the OAuth documentation for IdP setup.

Logging

Each server logs to stderr at info level by default.

• CB_MCP_LOG_LEVEL — off, error, warning, info (lifecycle events and tool calls) or debug.
• CB_MCP_LOG_SINKS — stderr, file, or both. With file, one rotating file per level is written next to CB_MCP_LOG_FILE (mcp_server.info.log, mcp_server.error.log, …).
• Rotation and retention — CB_MCP_LOG_ROTATION_MAX_SIZE_MB (default 1 MB) and CB_MCP_LOG_RETENTION_BACKUP_COUNT (default 1) apply to every level; override per level with CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB / CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT. Invalid sizes fall back to the default with a startup warning. CB_MCP_LOG_MAX_BYTES is deprecated.
• Config snapshot — with the file sink, a JSON record of the environment and redacted server config is written to mcp_server_config.log.json on every start, for support.

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

Your MCP client usually also captures the server's stderr — see Client Setup for where. Details: logging documentation.

Auditing

Audit logging records who did what, and whether it was allowed — separate from the operational logs, which record what went wrong. The MCP server is the only layer that can answer this for an agent: every request reaches the cluster as a single database user, and decisions such as a scope denial, a read-only block or a declined confirmation never reach the cluster at all.

Auditing is off by default. Turn it on with CB_MCP_AUDIT_LOG_ENABLED=true; it writes to stderr unless you set CB_MCP_AUDIT_LOG_SINKS=file and CB_MCP_AUDIT_LOG_FILE_PATH.

# 90 days of daily, gzipped audit files
uvx couchbase-mcp-server operational --audit-log-enabled=true \
  --audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
  --audit-log-rotation-interval=1d --audit-log-rotation-max-size-mb=0 \
  --audit-log-retention-max-backups=90

Records are JSON Lines using the same field vocabulary as Couchbase Server and Sync Gateway:

{"id":61522,"name":"document write","description":"A document write operation was requested through a tool","timestamp":"2026-09-29T09:14:22.418Z","real_userid":{"domain":"oauth","user":"agent-svc-7"},"server":{"version":"1.0.2","host":"mcp-01"},"cid":"9f2c...","outcome":"success","tool_name":"upsert_document_by_id","required_scope":"write","ks":"travel-sample.inventory.airline","cb_userid":"mcp_service"}

Client Setup

Each client needs a server configuration from the operational or Operational Insights quick start in its own configuration location. The examples below use the operational server.

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

Docker

Prebuilt images are published to Docker Hub as couchbase/mcp-server, and the server is listed in the Docker MCP Catalog. Configure the container with the same environment variables as above. See the Docker Hub page (DOCKER.md) for tags, volumes and health-check examples.

Running over HTTP — note that the server must bind to 0.0.0.0 to be reachable from outside the container:

docker run --rm \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT=http \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 8000:8000 \
  couchbase/mcp-server:latest operational

• If Couchbase runs on your host machine, use couchbase://host.docker.internal as the connection string (see Docker networking). Use --network=<your_network> to join another container's network.
• Append operational-insights instead of operational to run the Operational Insights server (port 8001).

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 .

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

Troubleshooting

• Check the connection string, username/password or certificate paths.
• For Capella, make sure the cluster allows connections from the machine running the server.
• Make sure the database user can access at least one bucket.
• If the client can't find uv/uvx, put the absolute path in command.
• When running from source, check the repository path in the configuration, and run uv sync after pulling updates.
• Call get_server_configuration_status to see the configuration the server actually resolved, and check your client's logs (see Client Setup).

FAQ

How do I connect Claude Desktop to Couchbase? Add the quick start configuration to claude_desktop_config.json and restart Claude Desktop — see Client Setup.

Can I use this with Couchbase Capella? Yes, with the operational server: the same configuration works for Capella and self-managed clusters, though a few admin tools are only available on self-managed clusters (see Tools). The Operational Insights server is for self-managed Operational Insights clusters only.

Is it safe to let an AI agent write to my database? By default, no write tools are loaded and modifying SQL++ is blocked. If you enable writes, you can still disable individual tools or require confirmation — but your Couchbase user's RBAC permissions remain the real security boundary. See Safety Controls.

Do I need to know SQL++? No. Ask in plain English and the assistant writes the SQL++ for run_sql_plus_plus_query. It can also explain a query plan or ask the Index Advisor for recommendations.

STDIO, Streamable HTTP or SSE? STDIO for a single local client. Streamable HTTP to share one server between clients, with OAuth. SSE is deprecated. See Transports.

Is this officially supported by Couchbase? Yes, with a Couchbase AI Data Plane license. Without one, Couchbase engineers help on a best-effort basis through GitHub issues. See Support Policy.

Contributing

Contributions are welcome — bug fixes, features and documentation. To report a bug or ask for help, open a GitHub issue.

See CONTRIBUTING.md for development setup, linting, testing, project structure and workflow. To get started:

git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase
uv sync --extra dev
uv run pre-commit install
./scripts/lint.sh

Integration tests run against a live cluster. Export CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD and optionally CB_MCP_TEST_BUCKET; the Operational Insights tests also use CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / _USERNAME / _PASSWORD and are skipped when those are unset. Then run:

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

Usage Data, LLM Risks and Support Policy

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.

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.

Support Policy

Couchbase MCP Server is open source and maintained by Couchbase engineers. How you get help depends on how you use it:

• Community use — report bugs, ask questions and request features by opening a GitHub issue. Couchbase engineers monitor the repository and respond on a best-effort basis, with no response-time commitment. The Couchbase support portal cannot help with community use.
• Enterprise support — available by licensing Couchbase AI Data Plane, which also covers Couchbase Agent Memory and Couchbase Agent Catalog. Licensed customers get help through their usual Couchbase Support channels.

Thank you for using and contributing to the project!