Couchbase MCP Server

Model Context Protocol (MCP) server that connects AI assistants and agents to Couchbase — locally or over SSH tunnels to remote clusters.

Features

Safety

• Read-only mode (default): Blocks write operations during exploration
• Write confirmation: Destructive tools require explicit approval
• Tool disabling: Turn off specific tools via CB_DISABLED_TOOLS

Performance

• HTTP wrapper: Management and query APIs with SDK fallback
• Large result handling: Truncation and export for oversized documents and query results
• WAN development profile: Tuned for tunneled / remote clusters

Tools (24)

Category	Tools
Cluster	connection test, config status, buckets, scopes, collections, health
KV	get, lookup-in, upsert, insert, replace, delete
Query	N1QL, cluster queries, schema inference, slow/frequent/large query analysis
Index	list indexes, advisor recommendations

Prerequisites

• Python 3.10+
• Couchbase Server 7.0+ (local or remote)
• jq for environment switching
• SSH key for tunneled environments
• An MCP client (e.g. Claude Code, Cursor)

Quick start

git clone https://github.com/nethanchowdary/couchbase-mcp-server.git
cd couchbase-mcp-server

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Edit .env with your Couchbase connection details

Register with Claude Code

claude mcp add couchbase -s user \
  -e "COUCHBASE_SERVER_DIR=$(pwd)" \
  -- python -m couchbase_mcp_server.server

Restart the MCP server after config changes:

claude mcp restart couchbase

Register with Cursor

Add to your MCP config (Settings → MCP):

{
  "mcpServers": {
    "couchbase": {
      "command": "/path/to/couchbase-mcp-server/.venv/bin/python",
      "args": ["-m", "couchbase_mcp_server.server"],
      "env": {
        "COUCHBASE_SERVER_DIR": "/path/to/couchbase-mcp-server"
      }
    }
  }
}

Environment switching

Use ./switch.sh to move between local Couchbase, SSH-tunneled clusters, and direct remote hosts without hand-editing .env.

./switch.sh list              # Show environments from environments.json
./switch.sh local             # Local Couchbase
./switch.sh remote-tunnel     # Remote via SSH tunnel (example config)
./switch.sh status            # Current env + tunnel state

On first switch to an environment you will be prompted for:

• Couchbase username and password (cached in ~/.couchbase-mcp/credentials.json, mode 600)
• SSH username (tunnel environments only)

Then choose read-only mode and optional tool disables. Restart MCP after switching:

claude mcp restart couchbase

Configure environments

environments.json — committed example configs (local, remote-tunnel, remote-multinode, remote-direct). Edit hostnames and tunnel targets for your setup.

environments.local.json — optional, gitignored. Copy from environments.local.json.example for private clusters you do not want in git. Entries are merged on top of environments.json.

cp environments.local.json.example environments.local.json
# Edit with your real bastion hosts and node addresses

Credential management

./switch.sh credentials list
./switch.sh credentials clear remote-tunnel
./switch.sh credentials clear-all

Configuration reference

Variable	Required	Description
CB_CONNECTION_STRING	Yes	e.g. couchbase://localhost
CB_USERNAME	Yes	Couchbase user
CB_PASSWORD	Yes	Couchbase password
CB_READ_ONLY_MODE	No	Default true
CB_DISABLED_TOOLS	No	Comma-separated tool names
CB_TIMEOUT_SECONDS	No	Connection timeout
CB_CA_CERT_PATH	No	TLS CA cert
CB_CLIENT_CERT_PATH	No	mTLS client cert
CB_CLIENT_KEY_PATH	No	mTLS client key
LOG_LEVEL	No	Default INFO
COUCHBASE_SERVER_DIR	No	Project root for .env discovery

See .env.example for the full list.

SSH tunnels

tunnel-manager.sh handles single-node and multi-node tunnels. Multi-node setups may require localhost aliases on macOS:

sudo ifconfig lo0 alias 127.0.0.2 up

Test tunnel connectivity:

./switch.sh remote-tunnel --test
curl -u user:pass http://127.0.0.1:8091/pools/default

Development

source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check src tests

Or use the wrapper:

./run_mcp_server.sh

Security notes for public repos

• Never commit .env, environments.local.json, or credential files
• Rotate any Couchbase or SSH credentials that were ever committed or shared
• VITE_*-style exposure does not apply here (server-side env), but .env is still regenerated by switch.sh with passwords — keep it gitignored
• Use read-only Couchbase users when exploring production-like data

Project layout

src/couchbase_mcp_server/   # MCP server and tools
lib/credentials.sh          # Credential cache helpers
switch.sh                   # Environment switcher
tunnel-manager.sh           # SSH tunnel lifecycle
environments.json           # Example environment definitions
tests/

License

MIT (add a LICENSE file if you publish publicly).