capella-mcp-server

khanium/capella-mcp-server

3.1

If you are the rightful owner of capella-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Couchbase MCP Server is a FastAPI-based server designed for managing and interacting with Couchbase clusters and Capella cloud services through REST API endpoints.

Couchbase MCP Server

A FastAPI-based Model Context Protocol (MCP) server for interacting with Couchbase clusters and Capella cloud services. This server provides REST API endpoints for managing buckets, scopes, collections, documents, queries, and cluster health.

Features

Core Cluster Operations

  • List all buckets in the cluster
  • List scopes and collections
  • Get/upsert/delete documents by ID
  • Get collection structure (schema inference)
  • Run SQL++ queries with read-only protection

Status and Health

  • Check cluster credentials
  • Get cluster health and running services
  • Get MCP server status

Capella Integration

  • Management API: Deploy and manage Capella clusters and app services
  • Data API: Access cluster data via Capella's Data API

Security

  • Read-only query mode enabled by default (CB_MCP_READ_ONLY_QUERY_MODE=true)
  • Blocks write operations (INSERT, UPSERT, UPDATE, DELETE, etc.) in read-only mode
  • Allows only SELECT, EXPLAIN, and ADVISE queries when read-only mode is enabled
  • Per-request credential overrides via headers

Installation

Prerequisites

  • Python 3.11.x (project targets 3.11; see virtual environment section)
  • Access to a Couchbase cluster or Capella account

Dependencies

The following library versions are required (as specified in requirements.txt):

  • fastapi==0.109.0
  • uvicorn[standard]==0.27.0
  • pydantic==2.12.4
  • pydantic-settings==2.12.0
  • couchbase==4.5.0
  • httpx==0.28.1
  • python-dotenv==1.2.1
  • pytest==9.0.0
  • pytest-asyncio==1.3.0

Setup

  1. Clone the repository:
git clone <repository-url>
cd capella-mcp
  1. Create and activate a virtual environment (recommended):
# with pyenv (recommended)
pyenv install 3.11.14 -s
pyenv local 3.11.14

# create venv
python -m venv .venv
source .venv/bin/activate

Alternatively, use the Makefile targets:

make venv
make install
  1. Install dependencies:
pip install -r requirements.txt
  1. Create a .env file in the root directory:
# Couchbase Cluster Settings
CB_CLUSTER_URL=couchbases://your-cluster.couchbase.com
CB_USERNAME=your_username
CB_PASSWORD=your_password
CB_DEFAULT_BUCKET=default
CB_DEFAULT_SCOPE=_default

# MCP Server Settings
CB_MCP_READ_ONLY_QUERY_MODE=true

# Timeout Settings (milliseconds)
CB_CONN_TIMEOUT_MS=10000
CB_QUERY_TIMEOUT_MS=75000

# Capella Management API (optional)
CAPELLA_API_KEY=your_api_key
CAPELLA_API_SECRET=your_api_secret
CAPELLA_BASE_URL=https://api.cloud.couchbase.com

# Capella Data API (optional)
CAPELLA_DATA_API_BASE_URL=https://data-api.cloud.couchbase.com
CAPELLA_DATA_API_KEY=your_data_api_key
  1. Run the server:
python -m app.main

The server will start on http://localhost:8000

  1. Access the API documentation:

Docker

Build the image:

docker build -t couchbase-mcp .

Run the container:

docker run -d \
  --name couchbase-mcp \
  -p 8000:8000 \
  --env-file .env \
  couchbase-mcp

API Endpoints

Buckets

List all buckets
curl http://localhost:8000/api/buckets
List scopes and collections in a bucket
curl http://localhost:8000/api/buckets/my_bucket/scopes-collections
List scopes in a bucket
curl http://localhost:8000/api/buckets/my_bucket/scopes
List collections in a scope
curl http://localhost:8000/api/buckets/my_bucket/scopes/my_scope/collections

Documents

Get a document by ID
curl http://localhost:8000/api/docs/buckets/my_bucket/scopes/my_scope/collections/my_collection/docs/doc123
Upsert a document
curl -X PUT http://localhost:8000/api/docs/buckets/my_bucket/scopes/my_scope/collections/my_collection/docs/doc123 \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "age": 30}'
Delete a document
curl -X DELETE http://localhost:8000/api/docs/buckets/my_bucket/scopes/my_scope/collections/my_collection/docs/doc123
Get collection structure
curl http://localhost:8000/api/docs/buckets/my_bucket/scopes/my_scope/collections/my_collection/structure

Queries

Run a SQL++ query
curl -X POST http://localhost:8000/api/query/buckets/my_bucket/scopes/my_scope/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM my_collection LIMIT 10"}'

Status

Get MCP server status
curl http://localhost:8000/api/status
Check cluster credentials
curl -X POST http://localhost:8000/api/status/check-credentials
Get cluster health
curl http://localhost:8000/api/status/cluster-health

Capella Management API

List organizations
curl http://localhost:8000/api/capella/organizations
List clusters in a project
curl http://localhost:8000/api/capella/organizations/{org_id}/projects/{project_id}/clusters
Create a cluster
curl -X POST http://localhost:8000/api/capella/organizations/{org_id}/projects/{project_id}/clusters \
  -H "Content-Type: application/json" \
  -d '{
    "cloud_provider": "aws",
    "couchbase_server": "7.2",
    "group": {
      "compute": {
        "cpu": 4,
        "ram": 16
      },
      "disk": {
        "storage": 50,
        "type": "gp3"
      },
      "numOfNodes": 3
    },
    "name": "my-cluster"
  }'

Capella Data API

Get a document
curl http://localhost:8000/api/capella/data/kv/my_bucket/my_scope/my_collection/doc123
Upsert a document
curl -X PUT http://localhost:8000/api/capella/data/kv/my_bucket/my_scope/my_collection/doc123 \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "age": 25}'

Per-Request Credentials

You can override cluster credentials per-request using headers:

curl http://localhost:8000/api/buckets \
  -H "x-cb-cluster-url: couchbases://another-cluster.couchbase.com" \
  -H "x-cb-username: different_user" \
  -H "x-cb-password: different_password"

For Capella APIs:

curl http://localhost:8000/api/capella/organizations \
  -H "x-capella-api-key: your_api_key" \
  -H "x-capella-api-secret: your_api_secret"

curl http://localhost:8000/api/capella/data/kv/bucket/scope/collection/doc \
  -H "x-capella-data-api-key: your_data_api_key"

Read-Only Query Mode

By default, the server runs in read-only query mode. This means:

  • ✅ Allowed: SELECT, EXPLAIN, ADVISE queries
  • ❌ Blocked: INSERT, UPSERT, UPDATE, DELETE, MERGE, CREATE, ALTER, DROP, etc.

Note: Document operations (get/upsert/delete by ID) are not affected by this setting.

To disable read-only mode, set in .env:

CB_MCP_READ_ONLY_QUERY_MODE=false

Error Handling

The server returns standard HTTP status codes:

  • 200: Success
  • 400: Bad request (e.g., invalid query in read-only mode)
  • 401: Unauthorized (invalid credentials)
  • 404: Not found
  • 500: Internal server error

Error responses include a detail field with the error message.

Development

Running Tests

pytest tests/

Code Structure

app/
├── main.py                      # FastAPI application
├── config.py                    # Configuration settings
├── deps.py                      # Dependency injection
├── clients/                     # Client implementations
│   ├── couchbase_client.py      # Couchbase SDK client
│   ├── capella_management_client.py  # Capella Management API
│   └── capella_data_client.py   # Capella Data API
├── routers/                     # API route handlers
│   ├── buckets.py               # Bucket/scope/collection operations
│   ├── docs.py                  # Document operations
│   ├── query.py                 # Query operations
│   ├── status.py                # Status and health
│   └── capella.py               # Capella API endpoints
└── utils/                       # Utilities
    └── query_guard.py           # Query validation

License

[Your License Here]

Contributing

[Contributing Guidelines Here]