Couchbase MCP Server Cluster Data Access

Overview

The Couchbase MCP Server provides a lightweight HTTP interface for accessing and managing Couchbase cluster data using the Model Context Protocol (MCP). It acts as a bridge between Couchbase clusters and external tooling or AI systems that need structured, secure access to cluster information and documents without embedding Couchbase SDKs directly in every client.

For developers, the MCP server simplifies common tasks — discovering clusters, listing buckets/scopes/collections, performing KV operations, and running N1QL queries — through a consistent JSON/HTTP API. This is useful for integration, automation, and building services that must query or update Couchbase data while centralizing authentication, observability, and policy enforcement.

Features

• Exposes Couchbase cluster metadata (clusters, buckets, scopes, collections) via HTTP
• KV operations: fetch, upsert, remove documents by ID
• N1QL query endpoint for ad-hoc and parameterized queries
• Authentication and secure connections to Couchbase clusters (configurable)
• Centralized access point for integrating Couchbase with automation tools, AI systems, or microservices
• Simple JSON/HTTP API that fits into existing web-based workflows and scripts

Installation / Configuration

The MCP server can be run from source or as a container. Below are example configuration options and common run commands.

Environment variables (typical):

Example: run with Docker (replace placeholders):

docker run --rm -p 8080:8080 \
  -e COUCHBASE_CONNSTRING="couchbase://cb.example.local" \
  -e COUCHBASE_USERNAME="admin" \
  -e COUCHBASE_PASSWORD="secret" \
  couchbase-ecosystem/mcp-server-couchbase:latest

Run from source (Go environment assumed):

git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git
cd mcp-server-couchbase
go build ./cmd/mcp-server
COUCHBASE_CONNSTRING="couchbase://127.0.0.1" \
COUCHBASE_USERNAME="Administrator" \
COUCHBASE_PASSWORD="password" \
./mcp-server --bind 0.0.0.0:8080

Configuration file (JSON example):

{
  "couchbase": {
    "connString": "couchbase://127.0.0.1",
    "username": "admin",
    "password": "secret"
  },
  "server": {
    "bindAddr": "0.0.0.0:8080",
    "logLevel": "info"
  }
}

Available Resources

The MCP server typically exposes RESTful endpoints for cluster exploration and data operations. Common endpoints you can expect:

• GET /clusters — list configured/connected clusters
• GET /clusters/{cluster}/buckets — list buckets
• GET /clusters/{cluster}/buckets/{bucket}/scopes — list scopes & collections
• GET /clusters/{cluster}/buckets/{bucket}/docs/{id} — fetch document by ID
• PUT /clusters/{cluster}/buckets/{bucket}/docs/{id} — upsert document
• DELETE /clusters/{cluster}/buckets/{bucket}/docs/{id} — remove document
• POST /clusters/{cluster}/query — execute a N1QL query; JSON body with statement and optional params

The repository contains API examples and may include an OpenAPI/Swagger spec in the docs folder; check the GitHub project for the exact path and additional tooling.

GitHub: https://github.com/Couchbase-Ecosystem/mcp-server-couchbase

Use Cases

• Integration with AI/assistant tooling

  • Feed documents or query results to ML models without exposing Couchbase credentials to the model runtime.
  • Example: a system fetches user activity docs via MCP and passes them to a vectorization pipeline.

• Admin automation and scripting

  • Automate bucket and collection inspections, perform bulk updates, or run scheduled maintenance queries.
  • Example: a script polls GET /clusters/{cluster}/buckets to verify bucket health and then runs targeted N1QL for remediation.

• Microservice abstraction

  • Microservices call the MCP API to read/write documents, removing direct Couchbase SDK dependencies and centralizing access control.
  • Example: an edge service performs a PUT to /buckets/users/docs/{id} to update a profile without carrying SDK logic.

• Debugging and observability

  • Quickly inspect documents or run ad-hoc queries when diagnosing production issues, with centralized logging and auditing.
  • Example: use curl to fetch a document and record the request in centralized logs for incident analysis.

Example curl usage:

# Run a N1QL query
curl -X POST http://localhost:8080/clusters/default/query \
  -H "Content-Type: application/json" \
  -d '{"statement":"SELECT META().id, * FROM `travel-sample` LIMIT 5"}'

# Get a document
curl http://localhost:8080/clusters/default/buckets/users/docs/user::123

Notes and Next Steps

• Consult the repository for the exact API schema, authentication modes, and deployment examples.
• Secure production deployments with TLS, network controls, and proper Couchbase RBAC accounts.
• Extend or integrate the server into your tooling to centralize Couchbase access and simplify client-side code.