couchbase

Couchbase plugin for Claude Code

A Claude Code plugin for working with Couchbase — Capella or self-managed.

Wraps the open-source Couchbase MCP server so Claude can run SQL++ queries against your cluster, then adds a skill that teaches Claude the Couchbase-specific patterns it needs (META(), indexes, scopes/collections, etc.) and a /couchbase:explore command for inspecting a cluster.

Read-only by default. Safe to try on any cluster.

Install in 4 steps

1. Install prerequisites

You need Claude Code and uv (which provides uvx).

# uv — installs uvx too
curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal, then confirm:

which claude && which uvx

2. Get your Couchbase credentials ready

You need 4 things from your cluster:

For Capella: also add your machine's IP to Settings → Allowed IP Addresses. This is the #1 reason connections hang.

3. Install the plugin

Open Claude Code in any directory:

claude

Inside the session:

/plugin marketplace add midopooler/couchbase-plugin
/plugin install couchbase@couchbase-plugins
/exit

Note: installation requires a restart to activate.

4. Set env vars, then relaunch

In your terminal (paste one line at a time if your terminal mangles multi-line pastes):

export CB_CONNECTION_STRING='couchbases://cb.<your-id>.cloud.couchbase.com'
export CB_USERNAME='your_db_user'
export CB_[REDACTED:Password]
export CB_BUCKET_NAME='travel-sample'

claude

Inside the session, check it's wired up:

/mcp

You should see couchbase · ✔ connected. That's it — you're ready.

Try it

/couchbase:explore

…takes a tour of your cluster (scopes, collections, sample docs, indexes).

Then just ask questions in plain English:

• "Show me 5 airports in France."
• "Which airlines have the most routes? Top 10."
• "What's the shape of a document in the hotel collection?"
• "I want to query hotels by city. What index should I create?"

The plugin's skill kicks in automatically — Claude will use META().id, check indexes with EXPLAIN, prefer USE KEYS for direct lookups, and backtick-quote travel-sample correctly.

Making env vars stick

Tired of re-exporting every terminal? Add them to your shell profile once:

cat >> ~/.zshrc <<'EOF'

# Couchbase plugin
export CB_CONNECTION_STRING='couchbases://cb.<your-id>.cloud.couchbase.com'
export CB_USERNAME='your_db_user'
export CB_[REDACTED:Password]
export CB_BUCKET_NAME='travel-sample'
EOF

Then source ~/.zshrc or open a new terminal.

Enabling writes

Read-only query mode is on by default — inserts/updates/deletes will be blocked. To enable writes, set CB_MCP_READ_ONLY_QUERY_MODE=false before launching:

export CB_MCP_READ_ONLY_QUERY_MODE=false
claude

The skill still nudges toward safe patterns (CAS for optimistic concurrency, USE KEYS for direct KV, etc).

Troubleshooting

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

export NODE_TLS_REJECT_UNAUTHORIZED=0

export UV_NATIVE_TLS=true