AI导哈

Couchbase MCP 服务器

一个基于FastAPI的模型上下文协议（MCP）服务器，用于与Couchbase集群和Capella云服务交互，提供REST API端点以管理桶、范围、集合、文档、查询和集群健康状态。

  • by khanium
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 khanium/capella-mcp-server

使用说明

Couchbase MCP服务器

基于FastAPI的模型上下文协议（MCP）服务器，用于与Couchbase集群和Capella云服务交互。此服务器提供REST API端点，用于管理存储桶、作用域、集合、文档、查询和集群运行状况。

特性

核心集群运营

  • 列出集群中的所有bucket
  • 列出范围和集合
  • 按ID获取/追加销售/删除文档
  • 获取集合结构（模式推理）
  • 使用只读保护运行SQL++查询

状态和健康

  • 检查群集凭据
  • 获取群集运行状况和正在运行的服务
  • 获取MCP服务器状态

卡佩拉一体化

  • 管理API：部署和管理Capella集群和应用程序服务
  • 数据API：通过Capella的data API访问集群数据

安全

  • 默认情况下启用只读查询模式(CB_MCP_READ_ONLY_QUERY_MODE=true)
  • 以只读模式阻止写入操作（INSERT、UPSERT、UPDATE、DELETE等）
  • 启用只读模式时，仅允许SELECT、EXPLAIN和ADVISE查询
  • 通过标头覆盖每个请求的凭据

安装

先决条件

  • Python 3.11.x（项目目标3.11；见虚拟环境部分）
  • 访问Couchbase集群或Capella帐户

依赖项

需要以下库版本（如中所述 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

设置

  1. 克隆存储库：
git clone <repository-url>
cd capella-mcp
  1. 创建并激活虚拟环境（推荐）：
# with pyenv (recommended)
pyenv install 3.11.14 -s
pyenv local 3.11.14

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

或者，使用Makefile目标：

make venv
make install
  1. 安装依赖项：
pip install -r requirements.txt
  1. 创建一个 .env 根目录中的文件：
# 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. 运行服务器：
python -m app.main

服务器将于启动 http://localhost:8000

  1. 访问API文档：
  • Swagger用户界面：http://localhost:8000/docs
  • 重新记录：http://localhost:8000/redoc

码头工人

塑造形象：

docker build -t couchbase-mcp .

运行容器：

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

API终点

桶

列出所有桶

curl http://localhost:8000/api/buckets

在bucket中列出范围和集合

curl http://localhost:8000/api/buckets/my_bucket/scopes-collections

在bucket中列出作用域

curl http://localhost:8000/api/buckets/my_bucket/scopes

列出范围中的集合

curl http://localhost:8000/api/buckets/my_bucket/scopes/my_scope/collections

文件

按ID获取文档

curl http://localhost:8000/api/docs/buckets/my_bucket/scopes/my_scope/collections/my_collection/docs/doc123

插入文档

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}'

删除文档

curl -X DELETE http://localhost:8000/api/docs/buckets/my_bucket/scopes/my_scope/collections/my_collection/docs/doc123

获取集合结构

curl http://localhost:8000/api/docs/buckets/my_bucket/scopes/my_scope/collections/my_collection/structure

查询

运行SQL++查询

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"}'

状态

获取MCP服务器状态

curl http://localhost:8000/api/status

检查群集凭据

curl -X POST http://localhost:8000/api/status/check-credentials

获取群集运行状况

curl http://localhost:8000/api/status/cluster-health

Capella管理API

列出组织

curl http://localhost:8000/api/capella/organizations

列出项目中的集群

curl http://localhost:8000/api/capella/organizations/{org_id}/projects/{project_id}/clusters

创建集群

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数据API

获取文档

curl http://localhost:8000/api/capella/data/kv/my_bucket/my_scope/my_collection/doc123

插入文档

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}'

按请求凭据

您可以使用标头覆盖每个请求的群集凭据：

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"

对于卡佩拉原料药：

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"

只读查询模式

默认情况下，服务器以只读查询模式运行。这意味着：

  • ✅ 允许：选择、解释、建议查询
  • ❌ 已阻止：INSERT、UPSERT、UPDATE、DELETE、MERGE、CREATE、ALTER、DROP等。

注：文档操作（按ID获取/追加/删除）是 不 受此设置的影响。

要禁用只读模式，请在中设置 .env:

CB_MCP_READ_ONLY_QUERY_MODE=false

错误处理

服务器返回标准HTTP状态代码：

  • 200：成功
  • 400：请求错误（例如，只读模式下的查询无效）
  • 401：未经授权（无效凭据）
  • 404：未找到
  • 500：内部服务器错误

错误响应包括 detail 带有错误消息的字段。

发展

运行测试

pytest tests/

编码结构

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

许可证

[您的许可证在这里]

贡献

[此处为贡献指南]

相关 MCP