# MCP Server Couchbase

> MCP Server Couchbase is an open-source MCP server for databases. Self-hosted server for AI agents to query Couchbase, with read-only mode on by default. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** self-hosted, CLI
- **Website:** https://docs.couchbase.com/mcp-server/1.1/reference/common-overview.html
- **Repository:** https://github.com/couchbase/mcp-server-couchbase
- **MCP Registry name:** io.github.couchbase/mcp-server-couchbase
- **Categories:** databases
- **Listing updated:** 2026-11-15

## About

This server ships two servers in one package: one for Couchbase Server clusters on Capella or self-managed, and one for Operational Insights Enterprise, which is self-managed only. Tools cover cluster health, schema discovery, and query and index work.

Safe defaults matter here. Write tools are not loaded and data-modifying SQL++ queries are blocked unless CB_MCP_READ_ONLY_MODE is set to false. Individual tools can be disabled or require user confirmation, though the README says the Couchbase user's role-based access control remains the real security boundary.

It runs over stdio or Streamable HTTP with optional OAuth 2.1 for any IdP that publishes JWKS, with health checks and audit logging. Install from PyPI or Docker. It is tested with Claude Desktop, Cursor, Windsurf, VS Code and JetBrains AI Assistant or Junie, under Apache-2.0.

## Features

- **Two servers:** One package covers Couchbase Server and Operational Insights.
- **Read-only default:** Write tools are not loaded unless you turn writes on.
- **Tool controls:** Disable tools or require confirmation per tool.
- **Authentication options:** Basic, TLS and mTLS to the cluster, plus OAuth 2.1 over HTTP.
- **Audit logging:** Logging and auditing for shared deployments.
- **Multiple workers:** The operational server can use more CPU cores over HTTP.

## Good for

- Explore buckets, scopes and collection schemas
- Run SQL++ queries from an agent
- Check cluster health
- Inspect indexes before adding one

## Install

### Claude Code (Terminal)

```sh
claude mcp add mcp-server-couchbase --env CB_PASSWORD='<CB_PASSWORD>' --env CB_MCP_EMBEDDING_MODEL_API_KEY='<CB_MCP_EMBEDDING_MODEL_API_KEY>' --env CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID='<CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID>' --env CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY='<CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY>' -- uvx couchbase-mcp-server
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "mcp-server-couchbase": {
      "command": "uvx",
      "args": [
        "couchbase-mcp-server"
      ],
      "env": {
        "CB_PASSWORD": "<CB_PASSWORD>",
        "CB_MCP_EMBEDDING_MODEL_API_KEY": "<CB_MCP_EMBEDDING_MODEL_API_KEY>",
        "CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID": "<CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID>",
        "CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY": "<CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "mcp-server-couchbase": {
      "command": "uvx",
      "args": [
        "couchbase-mcp-server"
      ],
      "env": {
        "CB_PASSWORD": "<CB_PASSWORD>",
        "CB_MCP_EMBEDDING_MODEL_API_KEY": "<CB_MCP_EMBEDDING_MODEL_API_KEY>",
        "CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID": "<CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID>",
        "CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY": "<CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "mcp-server-couchbase": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "couchbase-mcp-server"
      ],
      "env": {
        "CB_PASSWORD": "<CB_PASSWORD>",
        "CB_MCP_EMBEDDING_MODEL_API_KEY": "<CB_MCP_EMBEDDING_MODEL_API_KEY>",
        "CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID": "<CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID>",
        "CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY": "<CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "mcp-server-couchbase": {
      "command": "uvx",
      "args": [
        "couchbase-mcp-server"
      ],
      "env": {
        "CB_PASSWORD": "<CB_PASSWORD>",
        "CB_MCP_EMBEDDING_MODEL_API_KEY": "<CB_MCP_EMBEDDING_MODEL_API_KEY>",
        "CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID": "<CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID>",
        "CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY": "<CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "mcp-server-couchbase": {
      "command": "uvx",
      "args": [
        "couchbase-mcp-server"
      ],
      "env": {
        "CB_PASSWORD": "<CB_PASSWORD>",
        "CB_MCP_EMBEDDING_MODEL_API_KEY": "<CB_MCP_EMBEDDING_MODEL_API_KEY>",
        "CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID": "<CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID>",
        "CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY": "<CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY>"
      }
    }
  }
}
```

## FAQ

### Can an agent modify data?

Not by default. Set CB_MCP_READ_ONLY_MODE=false to allow writes.

### How is it installed?

From PyPI as couchbase-mcp-server or via Docker.

### Which transports are supported?

stdio and Streamable HTTP (SSE is also a setting).

### Is enterprise support available?

Yes, through licensing Couchbase AI Data Plane.

### Is MCP Server Couchbase free?

Yes. MCP Server Couchbase is open source, so you can use and self-host it for free.

### How do I add MCP Server Couchbase to Claude Code?

Run this command in your terminal: claude mcp add mcp-server-couchbase --env CB_PASSWORD='<CB_PASSWORD>' --env CB_MCP_EMBEDDING_MODEL_API_KEY='<CB_MCP_EMBEDDING_MODEL_API_KEY>' --env CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID='<CB_MCP_EMBEDDING_MODEL_AWS_ACCESS_KEY_ID>' --env CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY='<CB_MCP_EMBEDDING_MODEL_AWS_SECRET_ACCESS_KEY>' -- uvx couchbase-mcp-server

### What are the best alternatives to MCP Server Couchbase?

The closest alternatives to MCP Server Couchbase are Midplane, PlatypusDB, Lorebase, Sovaria and model2data studio.

## Alternatives

- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [PlatypusDB](https://ai-powered.com/mcp/platypusdb): PlatypusDB is an open-source MCP server for databases.
- [Lorebase](https://ai-powered.com/mcp/lorebase): Lorebase is an open-source MCP server for knowledge and memory.
- [Sovaria](https://ai-powered.com/mcp/sovaria): Sovaria is a freemium MCP server for databases.
- [model2data studio](https://ai-powered.com/mcp/model2data-studio): model2data studio is a freemium MCP server for databases.
- [semlayer](https://ai-powered.com/mcp/semlayer): semlayer is a free MCP server for databases.
- [bricksentry](https://ai-powered.com/mcp/bricksentry): bricksentry is an open-source MCP server for databases.
- [MCP Toolbox for Databases](https://ai-powered.com/mcp/mcp-toolbox-for-databases-2): MCP Toolbox for Databases is an open-source MCP server for databases.

---
Source: https://ai-powered.com/mcp/mcp-server-couchbase
