MCP100 verdict
Not currently recommended. Shortlist — editorially admitted, not a Recommended endorsement.
MCP100 Assessment
Editorial verdict
Reviewed October 19, 2026
Task Fit
Mapped
Working with structured data
Trust
Status warning
Enable read-only and confirmation-required tools; precise tool surface config-dependent
Maintenance
Date unavailable
No dated repository or package update is currently stored.
Popularity
Signals available
Visible usage signals are shown for discovery only, not as proof of safety.
Evidence scope
34 MCP repository stars
1,200 package downloads / 30 days · Third-party: PyPI Stats
Repository identity: couchbase/mcp-server-couchbase
Package identity: couchbase-mcp-server · version 1.0.1.post1
Stars observed October 20, 2026 · Downloads observed October 20, 2026
Exact current first-party MCP repository; stars are MCP-specific repository evidence.
Exact MCP-specific PyPI package. Download count is the disclosed PyPI Stats `last_month` signal.
Publisher activity observed October 19, 2026
Current source snapshot
Source relationship: First-party MCP
Reviewed October 19, 2026
Evidence-backed setup
Choose your MCP client. A client connects to the MCP server; the language model is selected inside that client. Only stored, source-backed configurations are shown.
Transport not recorded
Complete client-specific setup, verification and removal are not documented in this reviewed source.
Publisher-documented setup is not the same as MCP100 execution testing. “MCP100 logic checked” means the stored configuration shape was reviewed, not that third-party MCP software was run.
Evidence checked 2026-10-19
Type-appropriate, source-backed setup for this mcp server profile.
Loading optional publisher installation details…
No complete evidence-backed client setup steps are currently stored. Optional publisher documentation may provide additional context below.
Capability
Couchbase MCP is a Couchbase MCP integration for couchbase query, collections and database troubleshooting. Use with Couchbase-backed applications. Query access can reveal customer records; write queries can modify production data.
Not measured yet
Estimated token footprint of the MCP tool schemas exposed to the agent.
couchbase/mcp-server-couchbase
Reviewed access
Related reviewed MCPs
Connect MCP clients to enterprise databases with prebuilt or explicitly defined tools.
Choose this instead if
Choose Google MCP Toolbox for Databases instead if schema exploration and database-aware coding in development environments.
Connect MCP clients to enterprise databases with prebuilt or explicitly defined tools.
Manage and search Redis data through Redis's MCP server.
Choose this instead if
Choose Redis MCP instead if inspecting and manipulating Redis strings, hashes, lists, sets, sorted sets, streams, JSON, and search indexes.
Manage and search Redis data through Redis's MCP server.
Connect AI tools to Supabase projects and development workflows.
Choose this instead if
Choose Supabase MCP instead if inspecting one Supabase project's schema, logs, advisors, and docs.
Connect AI tools to Supabase projects and development workflows.
Couchbase is listed as First-party MCP in MCP100’s current evidence.
Current official resources:
From the publisher README
Original client setup and configuration retained from the publisher documentation.
Publisher-documented clients
These names appear in the publisher's installation documentation. MCP100-verified configurations are shown separately above when available.
The MCP server can be run either from the prebuilt PyPI package or the source using uv.
We publish a pre built PyPI package for the MCP server.
{
"mcpServers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
or
{
"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
mcpServersobject.
The MCP server can be run from the source using this repository.
git clone https://github.com/couchbase/mcp-server-couchbase.git
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
mcpServersobject.
The server can be configured using environment variables or command line arguments:
| Environment Variable | CLI Argument | Description | Default |
|---|---|---|---|
CB_CONNECTION_STRING | --connection-string | Connection string to the Couchbase cluster | Required |
CB_USERNAME | --username | Username with access to required buckets for basic authentication | Required (or Client Certificate and Key needed for mTLS) |
CB_PASSWORD | --password | Password for basic authentication | Required (or Client Certificate and Key needed for mTLS) |
CB_CLIENT_CERT_PATH | --client-cert-path | Path to the client certificate file for mTLS authentication | Required if using mTLS (or Username and Password required) |
CB_CLIENT_KEY_PATH | --client-key-path | Path to the client key file for mTLS authentication | Required if using mTLS (or Username and Password required) |
CB_CA_CERT_PATH | --ca-cert-path | Path to server root certificate for TLS if server is configured with a self-signed/untrusted certificate. This will not be required if you are connecting to Capella | |
CB_MCP_READ_ONLY_MODE | --read-only-mode | Prevent all data modifications (KV, Query, scope/collection management, index management, and FTS index management). When enabled, write tools are not loaded. | true |
CB_MCP_TRANSPORT | --transport | Transport mode: stdio, http, sse | stdio |
CB_MCP_HOST | --host | Host for HTTP/SSE transport modes | 127.0.0.1 |
CB_MCP_PORT | --port | Port for HTTP/SSE transport modes | 8000 |
CB_MCP_WORKERS | --workers | Number of server worker processes for the http transport. Values above 1 run in stateless HTTP mode (see Multiple Workers) | 1 |
CB_MCP_STATELESS_HTTP | --stateless-http | Handle each HTTP request without per-session state. Only honored with http; cannot be combined with confirmation-required tools (see Multiple Workers) | true when workers > 1, otherwise false |
CB_MCP_DISABLED_TOOLS | --disabled-tools | Tools to disable (see Disabling Tools) | None |
CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | Tools that require explicit user confirmation before execution via MCP elicitation (see Elicitation/Confirmation Required Tools) | None |
CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE | --operational-insights-query-result-max-size | Maximum size in bytes of an Operational Insights query tool's result. Unset means no limit — the full result is returned. When set, rows are streamed from the cluster and reading stops once the budget is reached; the response then reports truncated: true along with a truncation object explaining what happened. The budget is a hard ceiling: a row that would overrun it is not returned, so a budget smaller than a single row yields no rows (reported explicitly, not as an empty result). Applies to operational_insights_run_query_sync and operational_insights_get_async_query_results. Values above 4194304 (4 MB) are clamped with a startup warning; there is no minimum | Unset (no limit) |
CB_MCP_LOG_LEVEL | --log-level | Logging level for the MCP server: off, debug, info, warning, error (see Logging) | info |
CB_MCP_LOG_SINKS | --log-sinks | Comma-separated log destinations: stderr, file, or both (see Logging) | stderr |
CB_MCP_LOG_FILE | --log-file | Base path for per-level log files (only used when the file sink is enabled) | mcp_server.log |
CB_MCP_LOG_ROTATION_MAX_SIZE_MB | --log-rotation-max-size-mb | Global maximum size in MB per log file before it rotates, inherited by every level unless overridden. 0 — or a value that cannot be used, such as a negative, nan or inf — is invalid and falls back to the default with a startup warning | 1 (1 MB) |
CB_MCP_LOG_MAX_BYTES | --log-max-bytes | Deprecated — use CB_MCP_LOG_ROTATION_MAX_SIZE_MB (MB). Global rotation size in bytes, still honored for backward compatibility; ignored when CB_MCP_LOG_ROTATION_MAX_SIZE_MB is also set | Unset |
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB | --log-error-rotation-max-size-mb | Rotation size in MB for the ERROR log file; overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for ERROR | Inherits CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB | --log-warning-rotation-max-size-mb | Rotation size in MB for the WARNING log file; overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for WARNING | Inherits CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB | --log-info-rotation-max-size-mb | Rotation size in MB for the INFO log file; overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for INFO | Inherits CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB | --log-debug-rotation-max-size-mb | Rotation size in MB for the DEBUG log file; overrides CB_MCP_LOG_ROTATION_MAX_SIZE_MB for DEBUG | Inherits CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_RETENTION_BACKUP_COUNT | --log-retention-backup-count | Rotated backup files kept per-level log file (excluding the live file), applied to every level unless overridden. 0 keeps only the live file (see Logging) | 1 |
CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT | --log-error-retention-backup-count | Rotated backups kept for the ERROR log file; overrides the global count for ERROR | Inherits CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT | --log-warning-retention-backup-count | Rotated backups kept for the WARNING log file; overrides the global count for WARNING | Inherits CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT | --log-info-retention-backup-count | Rotated backups kept for the INFO log file; overrides the global count for INFO | Inherits CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT | --log-debug-retention-backup-count | Rotated backups kept for the DEBUG log file; overrides the global count for DEBUG | Inherits CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_OAUTH_JWT_JWKS_URI | --oauth-jwks-uri | JWKS endpoint of the identity provider used to verify bearer JWTs. Enables OAuth when set with the issuer and audience (see OAuth 2.1 Authorization) | None |
CB_MCP_OAUTH_JWT_ISSUER | --oauth-issuer | Expected JWT iss claim. Required to enable OAuth | None |
CB_MCP_OAUTH_JWT_AUDIENCE | --oauth-audience | Expected JWT aud claim. Required to enable OAuth | None |
CB_MCP_OAUTH_JWT_ALGORITHM | --oauth-algorithm | JWT signing algorithm: one of RS256/384/512, ES256/384/512, PS256/384/512 | RS256 |
CB_MCP_OAUTH_MCP_BASE_URL | --oauth-mcp-base-url | Public base URL of this server. When set, publishes RFC 9728 Protected Resource Metadata so PRM-aware clients can discover the IdP | None |
CB_MCP_OAUTH_SCOPE_READ_LABEL | --oauth-scope-read-label | Override the OAuth scope label treated as 'read' access (advertised in PRM and matched against the token's scope/scp claim). Use when your IdP can't emit the canonical form | couchbase-mcp:read |
CB_MCP_OAUTH_SCOPE_WRITE_LABEL | --oauth-scope-write-label | Override the OAuth scope label treated as 'write' access; same semantics as the read label | couchbase-mcp:write |
CB_MCP_AUDIT_LOG_ENABLED | --audit-log-enabled | Enable audit logging — a separate sink from the CB_MCP_LOG_* operational logs, with a stable schema and its own retention (see Auditing) | false |
CB_MCP_AUDIT_LOG_SINKS | --audit-log-sinks | Comma-separated audit destinations: console, file, or both. console writes to stderr — never stdout, which carries the JSON-RPC protocol on stdio | console |
CB_MCP_AUDIT_LOG_FILE_PATH | --audit-log-file-path | Path to the audit log file. Required when file is in the sinks; the hostname and process id are inserted before the extension (audit.log → audit.<host>.<pid>.log) | None |
CB_MCP_AUDIT_LOG_ROTATION_MAX_SIZE_MB | --audit-log-rotation-max-size-mb | Maximum size in MB the live audit file may reach before it rotates. 0 turns size-based rotation off | 10 (10 MB) |
CB_MCP_AUDIT_LOG_ROTATION_INTERVAL | --audit-log-rotation-interval | Age the live audit file may reach before it rotates, as <value><unit> where the unit is d (24 hours) or w (7 days) — e.g. 1d, 30d, 8w. 0 turns interval-based rotation off | 1d |
CB_MCP_AUDIT_LOG_RETENTION_MAX_BACKUPS | --audit-log-retention-max-backups | Rotated backups retained per audit file, excluding the live file. Backups are gzipped. 0 keeps none. This bounds one file, not the directory — see Auditing | 10 |
CB_MCP_AUDIT_LOG_TOOL_ARGS | --audit-log-tool-args | Record tool argument values in the audit log. Off by default — there is no redaction in this release, so enabling it writes arguments verbatim, including full document bodies | false |
CB_MCP_AUDIT_LOG_DISABLED_EVENTS | --audit-log-disabled-events | Audit events to suppress: comma-separated numeric event ids (e.g. 61490,61491), or a file with one id per line. Only filterable events can be suppressed | None |
EMBEDDING_PROVIDER | --embedding-provider | Embedding provider for run_vector_query / run_vector_search: one of couchbase, openai, cohere, voyage, bedrock. Unset disables both tools' embedding step until configured — see Embedding Provider Configuration | None |
EMBEDDING_MODEL | --embedding-model | Model name/ID for the configured embedding provider | None |
EMBEDDING_API_KEY | --embedding-api-key | API key for the configured provider. Not used by bedrock (uses the AWS credential chain / EMBEDDING_AWS_* instead) | None |
EMBEDDING_ENDPOINT | --embedding-endpoint | Base URL override (an OpenAI-compatible local server, or a Couchbase Model Service deployment's own URL — required when EMBEDDING_PROVIDER=couchbase) | None |
EMBEDDING_AWS_ACCESS_KEY_ID | --embedding-aws-access-key-id | AWS access key ID, bedrock provider only. Omit to use the default AWS credential chain | None |
EMBEDDING_AWS_SECRET_ACCESS_KEY | --embedding-aws-secret-access-key | AWS secret access key, bedrock provider only | None |
EMBEDDING_AWS_REGION | --embedding-aws-region | AWS region, bedrock provider only. Falls back to the AWS SDK's own region resolution if unset | None |
CB_MCP_READ_ONLY_MODE is the single switch controlling write operations:
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.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 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:
EMBEDDING_PROVIDER | Required | Optional | Notes |
|---|---|---|---|
couchbase | EMBEDDING_API_KEY, EMBEDDING_MODEL, EMBEDDING_ENDPOINT | — | Couchbase's own Model Service (Provisioned/Serverless). EMBEDDING_ENDPOINT is this deployment's own base URL (e.g. https://<id>.ai.couchbase.com) — get it from Capella's AI Data Plane > Models UI. There is no shared default domain. |
openai | EMBEDDING_API_KEY, EMBEDDING_MODEL | EMBEDDING_ENDPOINT | Defaults to api.openai.com. Set EMBEDDING_ENDPOINT to point at an OpenAI-compatible local server (Ollama, vLLM, LM Studio) instead. |
cohere | EMBEDDING_API_KEY, EMBEDDING_MODEL | EMBEDDING_ENDPOINT | Defaults to api.cohere.com. |
voyage | EMBEDDING_API_KEY, EMBEDDING_MODEL | EMBEDDING_ENDPOINT | Defaults to api.voyageai.com. |
bedrock | EMBEDDING_MODEL | EMBEDDING_AWS_ACCESS_KEY_ID, EMBEDDING_AWS_SECRET_ACCESS_KEY, EMBEDDING_AWS_REGION | Titan embedding models only (e.g. amazon.titan-embed-text-v2:0). Omit the AWS credential fields to use the default AWS credential chain (env vars, ~/.aws/credentials, instance role). Requires the bedrock-embeddings extra: pip install couchbase-mcp-server[bedrock-embeddings] (or uv sync --extra bedrock-embeddings from source). |
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-..."
}
}
}
}
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.
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:
| Tool | Endpoint it needs |
|---|---|
get_cluster_metrics | Management REST (/pools/default/stats/range) |
get_cluster_tasks | Management REST (/pools/default/tasks) |
get_bucket_config | Management REST (/pools/default/buckets[/<name>]) |
get_cluster_health_snapshot | Management REST, plus per-node endpoints |
get_cluster_system_events | Management REST (/events) |
get_index_stats | Index Service REST (each indexer's /api/v1/stats) |
get_cluster_query_vitals | Query service REST (each query node's /admin/vitals) |
get_active_queries | Query service REST (each query node's /admin/active_requests) |
delete_active_query | Query service REST (DELETE /admin/active_requests/{id}) |
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.
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.
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"
}
}
}
}
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_idanddelete_document_by_id, data modifications can still occur via therun_sql_plus_plus_querytool using SQL++ DML statements (INSERT, UPDATE, DELETE, MERGE) unless:
- The
CB_MCP_READ_ONLY_MODEis set totrue(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.
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:
# 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:
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
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).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.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).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.
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"}
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.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.descriptor.json inside the package.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.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.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.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.audit.*.log* files.get_server_configuration_status reports the live written / dropped / write_errors counters, and dropped is the only way to discover that records were lost.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
Follow the steps below to use Couchbase MCP server with Claude Desktop MCP client
The MCP server can now be added to Claude Desktop by editing the configuration file. More detailed instructions can be found on the MCP quickstart guide.
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonOpen the configuration file and add the configuration to the mcpServers section.
Restart Claude Desktop to apply the changes.
You can now use the server in Claude Desktop to run queries on the Couchbase cluster using natural language and perform CRUD operations on documents.
Logs
The logs for Claude Desktop can be found in the following locations:
The logs can be used to diagnose connection issues or other problems with your MCP server configuration. For more details, refer to the official documentation.
Follow steps below to use Couchbase MCP server with Cursor:
Install Cursor on your machine.
In Cursor, go to Cursor > Cursor Settings > Tools & Integrations > MCP Tools. Also, checkout the docs on setting up MCP server configuration from Cursor.
Specify the same configuration manually, or use the one-click Install in Cursor link. You may need to add the server configuration under a parent key of mcpServers.
Note: The install link uses placeholder values from the configuration examples above. Update the connection string and credentials after installation.
Save the configuration.
You will see couchbase as an added server in MCP servers list. Refresh to see if server is enabled.
You can now use the Couchbase MCP server in Cursor to query your Couchbase cluster using natural language and perform CRUD operations on documents.
For more details about MCP integration with Cursor, refer to the official Cursor MCP documentation.
Logs
In the bottom panel of Cursor, click on "Output" and select "Cursor MCP" from the dropdown menu to view server logs. This can help diagnose connection issues or other problems with your MCP server configuration.
Follow the steps below to use the Couchbase MCP server with Windsurf Editor.
Install Windsurf Editor on your machine.
In Windsurf Editor, navigate to Command Palette > Windsurf MCP Configuration Panel or Windsurf - Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers. For more details on the configuration, please refer to the official documentation.
Click on Add Server and then Add custom server. On the configuration that opens in the editor, add the Couchbase MCP Server configuration from above.
Save the configuration.
You will see couchbase as an added server in MCP Servers list under Advanced Settings. Refresh to see if server is enabled.
You can now use the Couchbase MCP server in Windsurf Editor to query your Couchbase cluster using natural language and perform CRUD operations on documents.
For more details about MCP integration with Windsurf Editor, refer to the official Windsurf MCP documentation.
Follow the steps below to use the Couchbase MCP server with VS Code.
Install VS Code
Following are a couple of ways to configure the MCP server.
For a Workspace server configuration
For the Global server configuration:
Ctrl+Shift+P or Cmd+Shift+P)Note: VS Code uses servers as the top-level JSON property in mcp.json files to define MCP (Model Context Protocol) servers, while Cursor uses mcpServers for the equivalent configuration. Check the VS Code client configurations for any further changes or details. An example VS Code configuration is provided below.
{
"servers": {
"couchbase": {
"command": "uvx",
"args": ["couchbase-mcp-server"],
"env": {
"CB_CONNECTION_STRING": "couchbases://connection-string",
"CB_USERNAME": "username",
"CB_PASSWORD": "password"
}
}
}
}
Once you save the file, the server starts and a small action list appears with Running|Stop|n Tools|More...
Click on the options from the option list to Start/Stop/manage the server.
You can now use the Couchbase MCP server in VS Code to query your Couchbase cluster using natural language and perform CRUD operations on documents.
Logs:
In the Command Palette (Ctrl+Shift+P or Cmd+Shift+P),
Follow the steps below to use the Couchbase MCP server with JetBrains IDEs
Logs: The log file can be explored at Help > Show Log in Finder (Explorer) > mcp > couchbase
# 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
Original product, capability, tool, and usage documentation from the MCP publisher. Installation sections appear under Install & Agents.
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.
CB_MCP_READ_ONLY_MODE=false, and individual tools can be disabled or gated behind user confirmation.Once the server is connected, you can talk to your Couchbase cluster in natural language through your AI assistant. For example:
orders collection?"users collection where status = 'active'."products collection with these fields: ..." (requires CB_MCP_READ_ONLY_MODE=false)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.
| Tool Name | Description |
|---|---|
get_server_configuration_status | Get the server status and configuration without connecting to the cluster — reports read-only mode, disabled/confirmation-required tools, OAuth settings, and the resolved logging configuration |
test_cluster_connection | Check the cluster credentials by connecting to the cluster |
get_cluster_health_and_services | Get cluster health status and list of all running services, optionally filtered to specific services via service_types |
get_client_connectivity_report | Get the SDK's cached connection diagnostics — whether connections were already broken and for how long, without any active network probing |
get_cluster_metrics | Get one or more cluster statistics over a historic time window via the Management REST API's stats-range endpoint. Self-managed Couchbase Server 7.6+ only — not available on Capella. |
get_cluster_tasks | Get the cluster tasks running right now — rebalance, compaction, XDCR, index build — via the Management REST API's tasks endpoint. Returns the raw task array; fields vary by task type. Requires the Read-Only Admin (ro_admin) role. Self-managed Couchbase Server 7.6+ only — not available on Capella. |
get_cluster_health_snapshot | Get a per-node health snapshot — service topology, membership, orchestrator and a cluster health rollup — merged from the Management REST API's /pools/default, nodeServices and terseClusterInfo endpoints. Isolates a symptom to a specific node/service and flags which nodes are safe to act on. Requires the Read-Only Admin (ro_admin) role. Self-managed Couchbase Server 7.6+ only — not available on Capella. |
get_bucket_config | Get a bucket's configuration and live state — RAM quota, eviction policy, replica count, durability level, storage backend, conflict-resolution type, auto-compaction settings, and basic stats — via the Management REST API's bucket endpoint. Returns the raw bucket object unchanged; omit bucket_name to get every bucket at once. Requires the Read-Only Admin (ro_admin) role. Self-managed Couchbase Server 7.6+ only — not available on Capella. |
get_cluster_system_events | Get the cluster's system event log — configuration changes, failovers, rebalances and service restarts with timestamps — via the Management REST API's /events endpoint. Correlates a symptom with what changed and when. Returns events oldest-first with a summary of counts and time range; windowed with since_time and bounded (default 50 events) rather than returning the endpoint's 250. Requires the Full Admin or Cluster Admin role. Self-managed Couchbase Server 7.6+ only — not available on Capella. |
discover_tool_input_values | Look up the exact input values another tool needs, from reference data bundled with the server — currently every Couchbase Server metric name (type, unit, version added, description) for get_cluster_metrics. Browse by category or fuzzy-search by keyword. Works offline, without a cluster connection. |
| Tool Name | Description |
|---|---|
get_buckets_in_cluster | Get a list of all the buckets in the cluster |
get_scopes_in_bucket | Get a list of all the scopes in the specified bucket |
get_collections_in_scope | Get a list of all the collections in a specified scope and bucket. Note that this tool requires the cluster to have Query service. |
get_scopes_and_collections_in_bucket | Get a list of all the scopes and collections in the specified bucket |
get_schema_for_collection | Get the structure for a collection |
create_scope | Create a new scope in a bucket (Couchbase Server 7.6+ and Capella). Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
create_collection | Create a new collection in an existing scope (Couchbase Server 7.6+ and Capella). Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
delete_scope | Delete a scope and all its collections from a bucket — permanent. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
delete_collection | Delete a collection and all its documents from a scope — permanent. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
| Tool Name | Description |
|---|---|
get_document_by_id | Get a document by ID from a specified scope and collection |
lookup_subdocument | Look up parts of a document (specific fields, existence checks, or array/object counts) by path without fetching the whole document |
upsert_document_by_id | Upsert a document by ID to a specified scope and collection. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
insert_document_by_id | Insert a new document by ID (fails if document exists). Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
replace_document_by_id | Replace an existing document by ID (fails if document doesn't exist). Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
delete_document_by_id | Delete a document by ID from a specified scope and collection. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
mutate_subdocument | Modify parts of an existing document (upsert, insert, replace, remove, array ops, counters) by path without rewriting the whole document. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
| Tool Name | Description |
|---|---|
list_indexes | List all indexes in the cluster with their definitions, with optional filtering by bucket, scope, collection and index name. Each entry includes is_vector (and, when true, vector_type: hyperscale or composite). Set return_raw_index_stats=true to return the unprocessed index information. |
get_index_stats | Get per-index statistics (size, fragmentation, scan traffic, indexing lag) from the Index Service, per node. Names which index is responsible for disk or memory pressure, and identifies unused indexes. Self-managed Couchbase Server 7.6+ only — not available on Capella. |
get_index_advisor_recommendations | Get index recommendations from Couchbase Index Advisor for a given SQL++ query to optimize query performance |
create_index | Deprecated — use create_query_index instead. Create a scalar (non-vector) GSI secondary index on a collection. Deferred by default — call build_index afterward to build it. Kept for backward compatibility, removed in a future 2.0. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
create_query_index | Create a GSI index — scalar, Hyperscale vector, or Composite vector — via index_type, all through raw SQL++ (neither vector shape has an SDK management API). similarity and dimension are required for vector types, with no default. Deferred by default — call build_index afterward. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
build_index | Trigger the build of all deferred indexes on a collection. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
drop_index | Drop a GSI index (scalar or vector) from a collection. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
run_sql_plus_plus_query | Run a SQL++ query on a specified scope.Queries are automatically scoped to the specified bucket and scope, so use collection names directly (e.g., SELECT * FROM users instead of SELECT * FROM bucket.scope.users).CB_MCP_READ_ONLY_MODE is true by default, which means that all write operations (KV, Query, scope/collection management, index management, and FTS index management) are disabled. When enabled (i.e. CB_MCP_READ_ONLY_MODE=true), write tools are not loaded and SQL++ queries that modify data are blocked. |
explain_sql_plus_plus_query | Generate and evaluate an EXPLAIN plan for a SQL++ query. Returns query metadata, extracted plan, and plan evaluation findings. |
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.
| Tool Name | Description |
|---|---|
list_search_indexes | List Search (FTS) indexes. With no filters, lists cluster-level (legacy) indexes; with bucket_name, lists scope-level (scoped) indexes across every scope in that bucket; with bucket_name and scope_name, lists scope-level indexes in that one scope. |
get_search_index_definition | Get the full definition of a single Search index (mappings, analyzers, plan params). Pass bucket_name and scope_name together for a scope-level index, or omit both for a cluster-level (legacy) index. |
run_search | Run an FTS query against a Search index, or fetch its execution plan. query is the raw FTS query JSON body, supporting any non-vector query type (match, match_phrase, term, conjuncts, disjuncts, geo, date/numeric range, query_string, ...). Pass explain=true to fetch the execution plan instead of results — this still executes the query (limit defaulting to 1) since the Search service only exposes the plan per matched hit, not as a separate dry-run call. |
upsert_search_index | Create or update a Search (FTS) index definition (mappings, analyzers, plan params) — including a vector field mapping (type: "vector", with dims/similarity; note FTS's similarity values differ from GSI's). Works with both scope-level (scoped) and cluster-level (legacy) indexes. Pass bucket_name and scope_name together to target a scope-level index, or omit both for a cluster-level (legacy) index. Updating an existing index triggers a full rebuild — fetch the current definition with get_search_index_definition first and pass its uuid back to avoid clobbering concurrent changes. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
drop_search_index | Drop a Search (FTS) index. Works with both scope-level (scoped) and cluster-level (legacy) indexes. Pass bucket_name and scope_name together for a scope-level index, or omit both for a cluster-level (legacy) index. This permanently removes the index and cannot be undone — confirm the exact name and location with list_search_indexes first. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
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.
| Tool Name | Description |
|---|---|
run_vector_query | Embed a query and run a vector similarity search against a GSI vector index (Couchbase Server 8.0+), via SQL++'s APPROX_VECTOR_DISTANCE(). Unlike Search-service vector search, GSI selects the index automatically from the vector field referenced in the query — there is no index_name parameter. Returns full documents (or select_fields, if given); supports an optional raw SQL++ where prefilter and Hyperscale Vector Index tuning (num_probes/rerank/top_n_scan). |
run_vector_search | Run the Search service's vector search (Couchbase Server 7.6+) against a named Search index. Two independent, combinable options each take the same raw FTS query JSON body run_search accepts: scalar_query makes this a genuinely hybrid search (relevance-scored full-text matching and vector similarity both contribute to ranking), while prefilter narrows which documents the vector search is even allowed to consider as candidates before it runs — the Search-service equivalent of run_vector_query's where prefilter. Returns index-stored fields per hit, same as run_search (not full documents — follow up with get_document_by_id for those). |
| Tool Name | Description |
|---|---|
get_longest_running_queries | Get longest running queries by average service time |
get_most_frequent_queries | Get most frequently executed queries |
get_queries_with_largest_response_sizes | Get queries with the largest response sizes |
get_queries_with_large_result_count | Get queries with the largest result counts |
get_queries_using_primary_index | Get queries that use a primary index (potential performance concern) |
get_queries_not_using_covering_index | Get queries that don't use a covering index |
get_queries_not_selective | Get queries that are not selective (scans — secondary index, primary index, or sequential — return many more documents than final result) |
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.
| Tool Name | Description |
|---|---|
get_cluster_query_vitals | Get query-engine health (request rate, active/queued request counts, memory, GC, uptime) from every query-service node, via the Query service's /admin/vitals endpoint. Distinguishes "the workload is heavy" from "the query engine itself is stressed." Requires at minimum the Read-Only Admin (ro_admin) role. |
get_active_queries | Get all queries executing right now, merged across every query-service node, via the /admin/active_requests endpoint — elapsed time, statement, client, state. Requires at minimum the Read-Only Admin (ro_admin) role. |
delete_active_query | Cancel an in-flight query by its request ID via DELETE /admin/active_requests/{request_id}, trying every query node in turn. Requires the Full Admin or Cluster Admin role. Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
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.
| Tool Name | Description |
|---|---|
get_server_configuration_status | Get this server's status and configuration without connecting to a cluster — read-only mode, disabled/confirmation-required tools, OAuth settings, and the resolved logging configuration. Shared with the operational server: the same tool, registered by both. |
operational_insights_get_databases_in_cluster | List all databases in the Operational Insights cluster. |
operational_insights_get_scopes_in_database | List all scopes in a database. |
operational_insights_get_collections_in_scope | List all collections (datasets) in a scope. |
operational_insights_get_schema_for_collection | Infer the JSON schema of a collection by sampling documents. |
operational_insights_list_indexes | List secondary indexes via the System.Metadata.Index catalog (the SDK has no index manager). |
operational_insights_run_query_sync | Run a SQL++ statement (SELECT, DML, or DDL) and return its result rows, up to CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE when that is set (unset means no limit); a larger result is cut short and reported with truncated: true. Pass copy_to_link, copy_to_bucket and copy_to_path to export the rows to object storage instead of returning them (see Exporting large results). Enforces read-only mode server-side via QueryOptions(readonly=True) — there is no client-side SQL++ parser here. |
operational_insights_explain_query | Generate the query plan for a SQL++ statement via EXPLAIN, without executing it. |
operational_insights_create_index | Create a secondary index via CREATE INDEX (the SDK has no index manager). Disabled by default when CB_MCP_READ_ONLY_MODE=true. |
operational_insights_run_query_async | Start a SQL++ statement without waiting for it to finish, returning a query_handle token. Accepts the same copy_to_* export arguments as operational_insights_run_query_sync, and is the better choice for a large export since it does not hold the request open for the upload. Same read-only enforcement as operational_insights_run_query_sync. |
operational_insights_get_async_query_results | Check whether an async query has finished and, if so, return its rows (subject to the same CB_MCP_OPERATIONAL_INSIGHTS_QUERY_RESULT_MAX_SIZE budget, reported via truncated). For an exporting query it reports completion and names the destination instead of returning rows. Doubles as the status check — call again later if not yet ready. |
operational_insights_discard_async_query_results | Free a finished async query's result buffers on the server. Normal cleanup step after operational_insights_get_async_query_results. |
operational_insights_cancel_async_query | Stop an async query that is still running. Available in read-only mode: cancelling releases resources the caller allocated and does not modify stored data. A finished query cannot be cancelled — discard its results instead. |
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.
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.
| CLI Argument | Environment Variable | Description | Default |
|---|---|---|---|
--connection-string | CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING | Operational Insights endpoint URL (HTTP/HTTPS, not couchbase://) | None |
--username | CB_OPERATIONAL_INSIGHTS_USERNAME | Operational Insights username | None |
--password | CB_OPERATIONAL_INSIGHTS_PASSWORD | Operational Insights password | None |
--ca-cert-path | CB_OPERATIONAL_INSIGHTS_CA_CERT_PATH | Path to server root certificate (PEM), for verifying a self-signed/untrusted server certificate | None |
--client-cert-path | CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PATH | Path to the client certificate for mTLS authentication — a PEM cert (paired with --client-key-path) or a PKCS#12 bundle (.p12/.pfx, --client-key-path left unset). Requires an https:// --connection-string; overrides --username/--password when set | None |
--client-key-path | CB_OPERATIONAL_INSIGHTS_CLIENT_KEY_PATH | Path to the client certificate's private key (PEM). Leave unset when --client-cert-path is a PKCS#12 bundle | None |
--client-cert-password | CB_OPERATIONAL_INSIGHTS_CLIENT_CERT_PASSWORD | Decryption password for an encrypted client key or PKCS#12 bundle | None |
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.
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:
| Argument | Description |
|---|---|
copy_to_link | Name of an existing external link, created with CREATE LINK ... TYPE S3. Required. |
copy_to_bucket | Destination bucket in the external store. Required. |
copy_to_path | Path prefix within that bucket, e.g. exports/run1. Required. |
copy_to_format | json (default) or parquet. |
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:
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.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.
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.
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.
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:
http transport is required.--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).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.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:
--workers.{
"mcpServers": {
"couchbase-http": {
"url": "http://localhost:8000/mcp"
}
}
}
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.
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.
{
"mcpServers": {
"couchbase-sse": {
"url": "http://localhost:8000/sse"
}
}
}
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:
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.CB_MCP_OAUTH_MCP_BASE_URL additionally publishes RFC 9728 Protected Resource Metadata so PRM-aware clients can discover the authorization server.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.
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.
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 .
Alternatively, use the provided build script:
# Build with default image name (mcp/couchbase-src)
./build.sh
# Build with custom image name
./build.sh my-custom/image-name
This script automatically:
mcp/couchbase-src)latest, <short-commit>)Verify image labels:
# 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
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.
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.
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
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.--network=<your_network> option. The network you choose depends on your environment; the default is bridge. For details, refer to network drivers in docker.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.
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.uv sync to update the dependencies.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.
CB_CONNECTION_STRINGCB_USERNAMECB_PASSWORDCB_MCP_TEST_BUCKET (a bucket to probe during the tests)CB_OPERATIONAL_INSIGHTS_CONNECTION_STRING / CB_OPERATIONAL_INSIGHTS_USERNAME / CB_OPERATIONAL_INSIGHTS_PASSWORD.
Those tests skip automatically (not fail) when unset.uv run --extra dev pytest tests/integration -v
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.
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.
If you're interested in contributing code or setting up a development environment:
📖 See CONTRIBUTING.md for comprehensive developer setup instructions, including:
uvWe 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!