/couchbase-mcp

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,