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 querying is not supported by these tools (see Vector search tools below) — a vector field mapping in upsert_search_index is unaffected by this and already works.

Vector search tools

Both tools embed query text using the model configured via Embedding Provider Configuration — the caller passes plain text, never a raw vector. run_vector_query targets Couchbase Server 8.0+'s GSI vector indexes (Composite Vector Index / Hyperscale Vector Index) via SQL++; run_vector_search targets the Search service's vector search on Couchbase Server 7.6+. Available on both self-managed Couchbase Server and Capella.

Query performance analysis tools

Query service health tools

These reach the Query service's own N1QL Admin REST API, distinct from the SQL++ system-catalog-based tools above — they report the query engine's health directly, per node, and include the only remediation action in this group. Self-managed Couchbase Server 7.6+ only — not available on Capella.

Operational Insights tools

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

Every tool name below is prefixed with operational_insights_ (get_server_configuration_status excepted) so none can collide with the operational server's tool names, even if a single MCP client registers both servers at once.

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

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, create_query_index, build_index, drop_index; FTS index management: upsert_search_index, drop_search_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.

Embedding Provider Configuration

EMBEDDING_PROVIDER selects which model backend run_vector_query and run_vector_search embed query text with. It's entirely optional — the server starts fine with none of the EMBEDDING_* variables set, and both tools stay registered; calling either without a provider configured returns an error explaining what to set, rather than failing at startup or disappearing from tool discovery. Each provider needs a different subset of the EMBEDDING_* variables:

Example (OpenAI):

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "EMBEDDING_PROVIDER": "openai",
        "EMBEDDING_MODEL": "text-embedding-3-small",
        "EMBEDDING_API_KEY": "sk-..."
      }
    }
  }
}

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.

Tools disabled automatically by deployment

A few tools reach Couchbase through REST endpoints that Couchbase Capella does not expose. The server works out which kind of cluster CB_CONNECTION_STRING points at — Capella when every host ends in .cloud.couchbase.com, self-managed otherwise — and does not register the tools that cannot work there. They are reported alongside your own disabled tools by get_server_configuration_status, and listed in the startup log.

Today this affects the nine tools that reach Couchbase through an admin REST endpoint rather than the SDK, none of which are registered on a Capella connection:

Tools that go through the Couchbase SDK are unaffected and stay available on Capella — get_cluster_health_and_services (ping) and get_client_connectivity_report (diagnostics) among them.

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.

Confirmation needs an MCP session, so it cannot be used with stateless HTTP (--stateless-http, or --workers above 1). The server refuses to start with that combination rather than running the listed tools unconfirmed.

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. With multiple workers, each process's files also carry the host and process id (mcp_server.<host>.<pid>.info.log).
• 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.

Auditing

Audit logging answers a different question from the operational logs. Logs tell you what went wrong; the audit log tells you who did what, and whether it was allowed. It exists because the MCP server is the only layer that can answer either question about an agent: every request reaches the cluster as the single CB_USERNAME the server connects with, so Couchbase Server's own audit log cannot tell two callers apart — 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. CB_MCP_AUDIT_LOG_ENABLED=true turns it on, writing to the console (stderr) unless CB_MCP_AUDIT_LOG_SINKS says otherwise. A deployment that keeps records sets CB_MCP_AUDIT_LOG_SINKS=file and a path in CB_MCP_AUDIT_LOG_FILE_PATH; selecting the file sink without a path leaves the server running — with the console sink if one was also selected, otherwise with auditing off — and an error in the log.

Records are JSON Lines — one immutable record per line — using the same field vocabulary as Couchbase Server and Sync Gateway (id, name, description, timestamp, real_userid, server, cid, outcome, reason), so an existing audit pipeline gets one format across the estate.

{"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"}

• Identity — real_userid records the caller, in one of three domains: oauth (the bearer token's subject), local (the OS process owner, on stdio), or anonymous (HTTP with OAuth disabled). Enabling auditing on HTTP without OAuth warns at startup, because every record then resolves to anonymous.
• Correlation — cid groups every record produced by one request, so an authorization denial, a guardrail refusal and the eventual tool result join without matching on timestamps. There is deliberately no session identifier: MCP is moving to a stateless model in which connection identity must not be read as session continuity. For SQL++, the same cid is sent as the query's client_context_id, which Couchbase Server records as clientContextId — an exact join between the two logs.
• Events — a fixed catalogue on numbered ID blocks: server lifecycle and configuration, session initialize, token rejected, scope check denied, read-only write blocked, confirmation declined or skipped, and one read/write pair per tool category (cluster, schema, document, query, index, performance, search, config). Adding a tool needs no new ID and no change to a SIEM rule. The full catalogue ships as descriptor.json inside the package.
• Filtering — CB_MCP_AUDIT_LOG_DISABLED_EVENTS turns read noise down, taking numeric event ids (the id is the wire contract; event names are prose and may be reworded, so they are not accepted). Write and security events are not filterable: an attempt to disable one is refused with a warning, so the record of who changed what cannot be switched off by configuration.
• Rotation — two independent triggers, and either may be switched off with 0. CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB rotates the live file when it grows past a size; CB_MCP_AUDIT_LOG_ROTATION_INTERVAL rotates it when it grows older than an age (1d, 30d, 1w, 8w). Whichever falls due first rotates the file, and with both off the file simply keeps growing. The interval clock is anchored to the live file, not to startup, so a server that was down over the weekend rolls the stale file away rather than appending to it. A size that cannot be used — negative, nan, inf, or large enough to overflow the conversion to bytes — falls back to the default with a startup warning rather than preventing the server from starting.
• Retention and compression — CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS keeps that many rotated files beside the live one; 0 keeps none, truncating the live file at each rotation. Backups are named with the UTC rotation time (audit.<host>.<pid>.log.20261006T091422481503Z.gz) and gzipped, which matters because audit retention is measured in months — JSON Lines compresses roughly ten to one. The live file is deliberately left uncompressed so tail -f and grep still work during an incident.
• Per-writer files — the hostname and process id are inserted before the extension (audit.log → audit.<host>.<pid>.log), because a stdio deployment runs one server process per client and a shared rotating file would interleave and corrupt records. The hostname matters in containers: the published image's ENTRYPOINT is exec form, so the server is PID 1 in every container and a pid-only name would collide across containers sharing a volume.
• Retention is per file — the backup count bounds the rotated copies of one audit file. Every process, and so every stdio session and every restart, writes a new file with its own backups, and nothing prunes the files of processes that have exited. Total disk use therefore grows with the number of server starts; size the volume accordingly or sweep old audit.*.log* files.
• Fail-open — if the audit file cannot be written, the server keeps serving and the records are dropped and counted rather than turning an audit outage into a server outage. get_server_configuration_status reports the live written / dropped / write_errors counters, and dropped is the only way to discover that records were lost.
• Tool arguments — recorded only when CB_MCP_AUDIT_LOG_TOOL_ARGS is enabled, which warns at startup. There is no redaction in this release, so arguments are written verbatim, including the full document bodies passed to document-write tools.

Auditing applies to both servers. Each has its own Tier-2 event block, so an id names the server that emitted it: operational uses 0xF000 (61440), Operational Insights 0x10000 (65536). The two share the core block 0xE000 (57344) for lifecycle, session, authorization and guardrail events.

# Audit to the console (stderr) — no path needed
uvx couchbase-mcp-server --audit-log-enabled=true

# Audit to a file: daily rotation, 10 gzipped backups, both by default
uvx couchbase-mcp-server --audit-log-enabled=true \
  --audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log

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

# ~100 MB of records, ~20 MB on disk once gzipped
uvx couchbase-mcp-server --audit-log-enabled=true \
  --audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
  --audit-log-rotation-max-size-mb=10 \
  --audit-log-rotation-interval=0 \
  --audit-log-retention-max-backups=9

# One file, never rotated — keep everything
uvx couchbase-mcp-server --audit-log-enabled=true \
  --audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
  --audit-log-rotation-max-size-mb=0 --audit-log-rotation-interval=0 \
  --audit-log-retention-max-backups=0

# Turn down read noise, keeping every write and security event
uvx couchbase-mcp-server --audit-log-enabled=true \
  --audit-log-sinks=file --audit-log-file-path=/var/log/cb-mcp/audit.log \
  --audit-log-disabled-events="61490,61491"   # document read, query read

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_OPERATIONAL_INSIGHTS_CONNECTION_STRING=http://localhost:8095 \
  -e CB_OPERATIONAL_INSIGHTS_USERNAME=Administrator \
  -e CB_OPERATIONAL_INSIGHTS_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_OPERATIONAL_INSIGHTS_CONNECTION_STRING": "http://localhost:8095",
        "CB_OPERATIONAL_INSIGHTS_USERNAME": "Administrator",
        "CB_OPERATIONAL_INSIGHTS_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.

Exporting large results (Operational Insights)

A query whose result exceeds CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE (when that limit is set) comes back truncated, which is the right default for a tool whose output is read by an LLM — but sometimes the full data is what you need. operational_insights_run_query_sync and operational_insights_run_query_async can write the rows to external object storage instead of returning them, so the size of the result stops mattering.

Pass all three destination arguments:

The statement is wrapped in COPY ... TO and the tool 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. ..."
}

Notes:

• All three of link, bucket and path are required. A partial destination is rejected rather than quietly running the query and returning rows, which would write nothing and look like success.
• operational_insights_run_query_sync waits for the whole upload before returning, so the call takes as long as the copy does. For a large export prefer operational_insights_run_query_async, which returns a query_handle as soon as the query is submitted; operational_insights_get_async_query_results then reports completion and names the destination rather than returning rows.
• Exports are blocked in read-only mode. COPY ... TO writes data to external storage, so it requires CB_MCP_READ_ONLY_MODE=false (or a token carrying couchbase-mcp:write), even though the Operational Insights server itself classifies the statement as read-only.
• csv is not offered: the server requires a TYPE(...) clause naming the output schema for CSV, which cannot be inferred from an arbitrary SELECT.

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.

Multiple Workers

One server process uses at most about one CPU core. To use more cores, run several worker processes behind the same host and port:

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

A good starting point is the number of CPU cores available to the server. With more than one worker:

• The http transport is required.
• 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 when several replicas sit behind a load balancer without sticky sessions.
• --confirmation-required-tools cannot be used, since confirmation needs a session (see Elicitation/Confirmation for Tool Calls).
• Every process writes its own log files, named with the host and process id, for example mcp_server.<host>.<pid>.info.log: one set for the supervisor that starts the workers, and one per worker. A restarted worker starts a new set of files.
• The Operational Insights server supports only one worker, because its async query handles are held in process memory.

Health Check

In HTTP mode the server also answers GET /health (for example http://localhost:8000/health) with {"status": "ok", "server": "operational"}. Use it for container liveness probes and load-balancer health checks:

• It reports that the server process is up and serving HTTP. It does not connect to the cluster, so a cluster outage does not make healthy containers restart.
• It needs no authentication, even when OAuth is enabled; it returns nothing beyond the server name.
• It is served by every worker when running with --workers.

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_OPERATIONAL_INSIGHTS_CONNECTION_STRING / CB_OPERATIONAL_INSIGHTS_USERNAME / CB_OPERATIONAL_INSIGHTS_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.

How do I connect Claude Desktop to Couchbase? Install the server with uvx couchbase-mcp-server (or run it from source or Docker), then add its configuration to Claude Desktop's claude_desktop_config.json as shown in Configuration. Restart Claude Desktop and it will pick up the new tools.

Can I use this with Couchbase Capella? Yes. The same CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD (or mTLS certificate) configuration works for both Couchbase Capella and self-managed Couchbase Server clusters.

Is it safe to let an AI agent write to my database? By default, CB_MCP_READ_ONLY_MODE is true, so all write operations — document upserts/inserts/replaces/deletes and data-modifying SQL++ statements — are disabled and the write tools aren't even loaded. You can also disable individual tools (see Disabling Tools) or require explicit user confirmation before specific tools run (see Elicitation/Confirmation). Tool-level controls guide LLM behavior; your Couchbase user's RBAC permissions remain the real security boundary.

Can I run natural-language queries against my data without writing SQL++ myself? Yes — ask your AI assistant a question in plain English (e.g. "show me the 10 most recent orders over $100") and it can translate that into a SQL++ query using the run_sql_plus_plus_query tool. You can also ask the assistant to explain_sql_plus_plus_query a query or ask the index advisor for recommendations.

What's the difference between STDIO, Streamable HTTP, and SSE transport? STDIO is for a single local MCP client (e.g. Claude Desktop) launching the server as a subprocess. Streamable HTTP lets multiple clients share one running server instance over HTTP, and supports OAuth 2.1. SSE is the older HTTP transport, now deprecated by the MCP spec in favor of Streamable HTTP — see Streamable HTTP Transport Mode.

Is this officially supported by Couchbase? This project is Couchbase community-maintained — see Support Policy. Enterprise support is available separately through Couchbase AI Data Plane.

Contributing

We welcome contributions from the community! Whether you want to fix bugs, add features, or improve documentation, your help is appreciated.

If you need help, have found a bug, or want to contribute improvements, the best place to do that is right here — by opening a GitHub issue.

For Developers

If you're interested in contributing code or setting up a development environment:

📖 See CONTRIBUTING.md for comprehensive developer setup instructions, including:

• Development environment setup with uv
• Code linting and formatting with Ruff
• Pre-commit hooks installation
• Project structure overview
• Development workflow and practices

Quick Start for Contributors

# Clone and setup
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run linting
./scripts/lint.sh

📢 Support Policy

We truly appreciate your interest in this project! This project is Couchbase community-maintained, which means it's not officially supported by our support team. However, our engineers are actively monitoring and maintaining this repo and will try to resolve issues on a best-effort basis.

Our support portal is unable to assist with requests related to this project, so we kindly ask that all inquiries stay within GitHub.

Your collaboration helps us all move forward together — thank you!