Skip to main content
MCP server CX Codex

Couchbase — MCP server for Claude Code: what it does, how to install

A self-hosted MCP server that links AI agents to data in Couchbase clusters, on Capella or self-managed. The agent inspects the cluster, queries it and works with documents in plain language.

no license updated 2026-10-29

Open on GitHub

What Couchbase does

The server connects clients such as Claude Code, Cursor or Copilot to a Couchbase Server or Capella cluster. Through it an agent lists buckets, scopes and collections, explores schemas, issues SQL++ statements, runs full-text and vector search, reads and writes documents, and checks slow queries and cluster health.

It ships read-only: write tools stay unloaded and data-changing statements are blocked until CB_MCP_READ_ONLY_MODE=false is set. Single tools can be turned off or placed behind user confirmation. Two transports are available: STDIO for local clients and Streamable HTTP with OAuth 2.1 for shared setups.

Distribution goes through PyPI as couchbase-mcp-server and a couchbase/mcp-server image on Docker Hub; Python 3.11 or newer is required. The Couchbase account's RBAC roles stay the real security boundary, so even with writes enabled the agent cannot exceed its permissions.

What it helps with

  • list buckets, scopes and collections through an agent
  • turn a plain-language question into a SQL++ query
  • run full-text or vector search over Couchbase documents
  • read and update documents from the chat
  • troubleshoot slow queries and cluster issues

Example prompts for the agent

  • Show which buckets and collections this cluster has
  • Find documents from the last week in orders with SQL++
  • Run a vector search over the products collection and show the closest entries

How to install Couchbase

Install

The MCP registry has no launch command for it: see the repository README

Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more

Questions about Couchbase

How do I install the Couchbase MCP server?

It is published on PyPI as couchbase-mcp-server and as the couchbase/mcp-server image on Docker Hub. Once installed, register it in your MCP client with the cluster connection details.

What does the Couchbase MCP server do?

It gives an AI agent access to Couchbase data: cluster and schema inspection, SQL++ queries, full-text and vector search, document reads and writes, plus query and cluster diagnostics.

Can the agent modify data through this server?

Not by default. Read-only mode lifts only when CB_MCP_READ_ONLY_MODE=false is set, and the Couchbase account's RBAC roles remain the authoritative access boundary.

Similar MCP servers

All MCP servers for Data and databases →

Project sponsors

Companies that keep this analytics open