# 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](https://jqlang.github.io/jq/) for environment switching
- SSH key for tunneled environments
- An MCP client (e.g. Claude Code, Cursor)

## Quick start

```bash
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

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

Restart the MCP server after config changes:

```bash
claude mcp restart couchbase
```

### Register with Cursor

Add to your MCP config (Settings → MCP):

```json
{
  "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`.

```bash
./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:

```bash
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`.

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

### Credential management

```bash
./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:

```bash
sudo ifconfig lo0 alias 127.0.0.2 up
```

Test tunnel connectivity:

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

## Development

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

Or use the wrapper:

```bash
./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).