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)

Related MCP server: CockroachDB MCP Server

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

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).