| name | couchbase-mcp |
| description | Operate Couchbase clusters and Capella v4 through an MCP server. Primary target is celticht32/MCP-Couchbase (167 tools) for full data-plane AND cluster admin; also covers the official Couchbase-Ecosystem/mcp-server-couchbase (narrower, data-plane-only, community-maintained, enterprise-supported via AI Data Plane license) and when to pick which. Use whenever the user mentions Couchbase, buckets, scopes, collections, SQL++ / N1QL, KV ops, subdocument ops, FTS, vector indexes, XDCR, eventing, backup, encryption / KMIP / DARE, user lock/unlock, query performance, Index Advisor, synonyms (8.x), or Capella organizations / projects / clusters / database users / allowed CIDRs / app services. Use proactively for cluster admin (rebalance, failover, recovery, autofailover, autocompaction, logs, alerts, audit, password policy), RBAC design, troubleshooting Couchbase errors, operational runbooks (rolling upgrade, node add/remove, post-failover recovery, backup/restore, credential rotation), and observability. |
| license | MIT |
Couchbase MCP
A skill for operating Couchbase through an MCP server. Two servers cover this space, and they are not interchangeable — pick based on how much of the surface you need.
Which MCP server — read this first
| celticht32/MCP-Couchbase (this skill's primary) | Couchbase-Ecosystem/mcp-server-couchbase (official) |
|---|
| Maintainer | Independent (Chris Ahrendt / celticht32) | Couchbase-Ecosystem — community-maintained; NOT covered by Couchbase's support team unless licensed (see below) |
| Surface | ~167 tools: full data plane plus cluster admin (buckets/scopes/collections, users/RBAC, rebalance/failover/recovery, XDCR, eventing, backup, KMIP/DARE), 8.x features (vector indexes, synonyms, user lock), Capella v4 control plane, perf diagnostics | Deliberately narrow: bucket-scoped data plane only — Cluster Health, Data/Schema, Key-Value, Query, Performance (index list, Index Advisor, slow-query analysis) |
| Admin ops (create bucket, rebalance, failover, XDCR, eventing, backup, encryption) | Yes | No — not in scope |
| Capella control plane (orgs/projects/clusters/allowlists) | Yes (read-only capella_* tools) | No |
| Auth / runtime | Cluster creds + Capella API key; two server processes | Python 3.10+, PyPI/Docker; CB_CONNECTION_STRING + basic auth or mTLS; STDIO or Streamable HTTP; bucket-scoped |
| Safety | CB_MCP_READ_ONLY_MODE + per-tool confirm:true gate | CB_MCP_READ_ONLY_MODE / CB_MCP_READ_ONLY_QUERY_MODE (read-only query default) |
| Enterprise support | None (independent project) | Available by licensing Couchbase AI Data Plane, which also entitles Couchbase Agent Memory + Agent Catalog (GA 2026-06-30) |
How to choose:
- Cluster administration, XDCR, eventing, backup, encryption, Capella control-plane inspection, or perf-analysis beyond Index Advisor → celticht32/MCP-Couchbase. The official server can't do these.
- Just KV + SQL++ + schema/health/Index-Advisor on a single bucket, want the vendor-tracked package, or need enterprise support via an AI Data Plane license → the official Couchbase-Ecosystem server.
- Tool names below (
cb_*, admin_*, capella_*) are the celticht32 server's. The official server uses its own (shorter) tool names — check its README when connected to it. The two do not share a namespace.
Note: celticht32 contributed index-management tools upstream to the official server (PR #187). Overlap in the data-plane basics is expected; the admin surface is unique to celticht32/MCP-Couchbase.
The rest of this skill documents the celticht32/MCP-Couchbase server (~167 tools across 17 categories), covering the full Couchbase data-plane and cluster administration surface.
When this skill applies
Any time the user is working with Couchbase. The MCP server exposes tools across these areas:
- Data plane: KV operations (get/upsert/insert/replace/delete, multi-get, subdocument lookup_in/mutate_in), SQL++ queries, FTS search, analytics queries, transactions
- Cluster admin: buckets, scopes, collections, sample buckets, indexes (including vector indexes for 8.x), FTS index management, synonyms
- Operations: rebalance, failover, recovery, autofailover, autocompaction, logs, alerts, server groups
- Security: users, groups, roles, audit, password policy, security settings, lock/unlock (8.x)
- Cross-datacenter: XDCR replication, conflict logging (8.x)
- Advanced services: eventing functions, backup repositories, encryption (DARE), KMIP key management
- Diagnostics: query performance analysis (slowest queries, frequency analysis, covering-index gaps, schema inference, index advisor)
- Capella v4 control plane: read-only inspection of organizations, projects, clusters, database users, allowed CIDRs, API keys, app services
If a task touches any of the above, prefer this skill's tools. The list above is the menu — pick from it before reaching for raw REST API calls or another MCP server.
Quick orientation: pick the right reference
The 167 tools split into a few clusters that share connection settings, conventions, and gotchas. Read the reference that matches the task at hand — don't read all of them upfront:
| Task domain | Read this reference |
|---|
| KV CRUD, SQL++, query, subdoc, FTS, transactions, analytics | references/data-plane.md |
| Buckets, scopes, collections, users, groups, roles, cluster ops, XDCR | references/cluster-admin.md |
| Vector indexes, synonyms, KMIP, user lock/unlock, conflict logging | references/couchbase-8x.md |
| Capella organizations, projects, clusters, allowlists, API keys | references/capella-v4.md |
| Performance analysis, EXPLAIN, schema inference, index advisor | references/diagnostics.md |
| Anything destructive (delete, drop, restore, rebalance) | references/safety.md — read this BEFORE writing the call |
| RBAC design, audit strategy, password policy, KMIP-vs-DARE decision, network isolation | references/security-best-practices.md |
| Errors and unexpected results (connection failures, auth issues, query/index problems, replication lag, eventing failures) | references/troubleshooting.md |
| Multi-step procedures (rolling upgrade, add/remove node, post-failover recovery, restore from backup, credential rotation, enabling DARE) | references/operational-runbooks.md |
| Monitoring, alerting, Prometheus integration, what metrics matter | references/observability.md |
| "What's the tool name for X?" | references/tool-index.md |
Each reference is self-contained. The tool-index.md is the fastest path to the exact tool name when you already know what you want to do.
Two server instances (celticht32 distribution)
Within the celticht32/MCP-Couchbase distribution (not the official server), there are two separate MCP server processes because they need different credentials and talk to different APIs:
- Cluster server (default) — 151 tools talking to a specific Couchbase cluster via
CB_CONNECTION_STRING, CB_USERNAME, CB_PASSWORD. Most tools you'll use.
- Capella v4 server (separate) — 16 read-only tools talking to
cloudapi.cloud.couchbase.com via CAPELLA_API_KEY_SECRET (Bearer auth).
These have non-overlapping tool name prefixes:
- Cluster server tools:
cb_* (data plane) and admin_* (cluster admin)
- Capella server tools:
capella_*
When the user asks about "Capella" they may mean either:
- The control plane (the Capella SaaS dashboard concept — orgs, projects, IP allowlists, billing) → use
capella_* tools
- A cluster hosted on Capella (a specific deployment they're querying) → use
cb_* / admin_* tools, just with couchbases:// connection string and port 18091
If unclear, ask. The blast radius differs: control-plane tools are scoped to one Capella API key, cluster tools are scoped to one deployment's credentials.
Safety primer (read this even for "simple" tasks)
The MCP server itself enforces two safety mechanisms at the server.py layer:
- Read-only mode (
CB_MCP_READ_ONLY_MODE=true) filters destructive tools out of the tool listing entirely. If the user sets this, you won't even see tools like admin_bucket_delete — that's intentional. Don't try to work around it.
- Confirmation gate — destructive tools require
confirm: true in the arguments. If you call admin_bucket_delete without confirm:true, the server returns an error explaining what would have happened. Always describe the impact to the user FIRST, get confirmation, THEN pass confirm:true.
Categories of operations to think about twice before calling:
- Data destruction:
cb_delete, admin_bucket_delete, admin_bucket_flush, admin_scope_drop, admin_collection_drop, admin_index_drop, admin_fts_index_delete
- Cluster topology changes:
admin_rebalance_start, admin_failover_node, admin_recovery_set
- Security changes:
admin_user_delete, admin_user_lock, admin_security_set, admin_audit_set
- Replication / backup:
admin_xdcr_delete_replication, admin_backup_restore_run
- Encryption rotation:
admin_encryption_rotate, admin_kmip_rotate
See references/safety.md for the full taxonomy of destructive operations and how to surface them to the user.
Conventions for tool calls
A few patterns repeat across most tools and are worth knowing up front:
Connection scoping: Data-plane tools (cb_*) take the bucket / scope / collection from arguments when present, falling back to CB_BUCKET / CB_SCOPE / CB_COLLECTION env vars. Admin tools (admin_*) typically address cluster-scoped resources by name (e.g., a bucket name string) and don't need a default scope.
JSON in / JSON out: All tools return JSON. For tools that wrap REST endpoints, the response usually has a status field (ok / error) and a data field with the actual payload. For data-plane tools (cb_get, cb_query), the response is the document or query result rows directly.
Capella tools are read-only by design: There is no capella_cluster_create or capella_user_invite — those operations are deliberately out of scope. If the user needs to make changes to a Capella deployment, point them at the Capella web UI.
How to pick a tool when given a task
The naming is consistent enough that you can usually guess. But if you're unsure:
- Operation on data? →
cb_* (e.g., cb_get, cb_query, cb_lookup_in)
- Operation on a Couchbase resource (bucket/index/user)? →
admin_<resource>_<verb> (e.g., admin_bucket_create, admin_user_lock)
- Inspection of Capella SaaS structure? →
capella_<resource>_<verb> (e.g., capella_clusters_list)
- Performance analysis? →
cb_perf_* family (see references/diagnostics.md)
- Couchbase 8.x-specific? → check
references/couchbase-8x.md first; these tools fail loudly if you're connected to a 7.x cluster
If none of these patterns match the task, the operation may not be supported. Check references/tool-index.md for the full listing before concluding the MCP can't do it.
Examples of correct use
Example 1 — User asks "show me my buckets":
The right tool is admin_bucket_list. Don't run cb_query against system:keyspaces to enumerate — there's a direct tool for this.
Example 2 — User asks "what's slow in my workload?":
This is a query performance analysis task. Read references/diagnostics.md then call cb_perf_slowest_queries and cb_perf_most_frequent for a starting picture. Optionally follow up with cb_perf_not_using_covering_index to find missing-index opportunities.
Example 3 — User asks "create a vector index on my embedding field":
This is Couchbase 8.x-specific. Read references/couchbase-8x.md to understand the difference between Hyperscale and Composite vector indexes. The Hyperscale variant scales further but costs more; Composite is the default for most workloads. Then call admin_vector_index_create_composite or admin_vector_index_create_hyperscale with the bucket / scope / collection / field / dimension / similarity arguments.
Example 4 — User asks "what clusters do I have in Capella?":
This is the control plane (capella_*). Read references/capella-v4.md for the resource hierarchy. The walk-down is: capella_organizations_list → grab the orgId → capella_projects_list with that orgId → grab a projectId → capella_clusters_list with both. You can't list clusters without the orgId and projectId — Capella has no global cluster view across organizations.
Example 5 — User asks "delete bucket X":
Read references/safety.md BEFORE responding. Confirm with the user what they want, describe the impact ("this will delete the bucket and all its data; no recovery without backup"), get explicit confirmation, then call admin_bucket_delete with confirm: true. If CB_MCP_READ_ONLY_MODE=true is set, the tool won't be available — tell the user to either temporarily unset it or do this operation through the Couchbase web console.
Tool name reference
If you encounter references to older or alternative tool names for common operations, use this mapping:
| Alternative name | Tool name in this server |
|---|
get_document_by_id | cb_get |
upsert_document_by_id | cb_upsert |
insert_document_by_id | cb_insert |
replace_document_by_id | cb_replace |
delete_document_by_id | cb_delete |
run_sql_plus_plus_query | cb_query |
explain_sql_plus_plus_query | cb_explain_query |
get_schema_for_collection | cb_get_schema_for_collection |
get_index_advisor_recommendations | cb_index_advisor |
list_indexes | admin_index_list |
get_buckets_in_cluster | admin_bucket_list |
get_cluster_health_and_services | admin_cluster_status |
get_longest_running_queries | cb_perf_longest_running |
get_most_frequent_queries | cb_perf_most_frequent |
get_queries_not_selective | cb_perf_not_selective |
get_queries_not_using_covering_index | cb_perf_not_using_covering_index |
get_queries_using_primary_index | cb_perf_using_primary_index |
get_queries_with_large_result_count | cb_perf_large_result_count |
get_queries_with_largest_response_sizes | cb_perf_large_response_sizes |
