mcp/couchbase

Couchbase MCP Server

镜像概述和主要用途

Couchbase 是一个分布式文档数据库，具备强大的搜索引擎及内置的操作和分析能力。Couchbase MCP Server 是基于模型上下文协议（Model Context Protocol）构建的服务器镜像，用于简化 AI 应用与 Couchbase 数据库的集成，提供标准化的工具集以实现与 Couchbase 集群的交互。

基本信息

核心功能与特性

主要特性

• 基于分布式文档数据库 Couchbase，支持高可用集群部署
• 内置 SQL++ 查询引擎，支持复杂数据查询与分析
• 提供完整的数据操作工具集，覆盖文档增删改查、结构查询等场景
• 支持连接验证、配置检查等运维工具，简化集群管理
• 遵循模型上下文协议（MCP），可无缝集成到 AI 应用工作流

提供的工具集（11个）

使用场景和适用范围

1. AI 应用数据交互：作为 MCP Server 与 Claude 等 AI 模型集成，实现自然语言驱动的 Couchbase 数据操作
2. 自动化数据管理：通过工具集实现文档批量处理、结构验证等自动化任务
3. 集群监控与运维：使用连接测试、配置检查工具监控 Couchbase 集群状态
4. 查询开发与验证：通过 run_sql_plus_plus_query 工具快速测试 SQL++ 查询语句
5. 多环境部署：支持通过环境变量配置连接参数，适配开发、测试、生产等不同环境

详细使用方法和配置说明

环境变量配置

Docker 运行命令示例

bash
docker run -i --rm \
  -e CB_CONNECTION_STRING="couchbases://cb.example.com" \
  -e CB_USERNAME="Administrator" \
  -e CB_PASSWORD="<your-password>" \
  -e CB_BUCKET_NAME="my-bucket" \
  -e CB_MCP_READ_ONLY_QUERY_MODE="true" \
  mcp/couchbase

Docker Compose 配置示例

yaml
version: '3.8'
services:
  couchbase-mcp-server:
    image: mcp/couchbase
    environment:
      - CB_CONNECTION_STRING=couchbases://cb.example.com
      - CB_USERNAME=Administrator
      - CB_PASSWORD=<your-password>
      - CB_BUCKET_NAME=my-bucket
      - CB_MCP_READ_ONLY_QUERY_MODE=true
    restart: unless-stopped

工具详情说明

delete_document_by_id

功能：按 ID 删除指定文档
返回值：成功返回 True，失败返回 False

get_buckets_in_cluster

功能：获取集群中所有可访问的桶名称
返回值：桶名称列表

get_collections_in_scope

功能：获取指定桶和作用域中的所有集合名称

get_document_by_id

功能：从指定作用域和集合中按 ID 获取文档
返回值：文档内容（JSON 对象）
异常：文档不存在时抛出异常

get_schema_for_collection

功能：获取指定作用域中集合的 schema（通过 INFER 查询生成）
返回值：包含集合名称和 schema 的字典

get_scopes_and_collections_in_bucket

功能：获取桶中所有作用域及集合名称
返回值：以作用域名称为键、集合名称列表为值的字典

get_scopes_in_bucket

功能：获取指定桶中的所有作用域名称

get_server_configuration_status

功能：获取服务器状态和配置信息（无需建立集群连接）
用途：验证服务器是否运行及配置是否正确

run_sql_plus_plus_query

功能：在指定作用域上运行 SQL++ 查询并返回结果
返回值：查询结果列表（每个结果为 JSON 对象）

test_cluster_connection

功能：测试与 Couchbase 集群的连接（可选测试指定桶）
返回值：包含连接状态和集群基本信息的字典

upsert_document_by_id

功能：按 ID 插入或更新文档
返回值：成功返回 True，失败返回 False

MCP Server 集成配置示例

在 AI 应用中配置 MCP Server 示例（JSON 格式）：

json
{
  "mcpServers": {
    "couchbase": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "CB_CONNECTION_STRING",
        "-e",
        "CB_USERNAME",
        "-e",
        "CB_BUCKET_NAME",
        "-e",
        "CB_MCP_READ_ONLY_QUERY_MODE",
        "-e",
        "CB_PASSWORD",
        "mcp/couchbase"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://cb.example.com",
        "CB_USERNAME": "Administrator",
        "CB_BUCKET_NAME": "my-bucket",
        "CB_MCP_READ_ONLY_QUERY_MODE": "true",
        "CB_PASSWORD": "<your-password>"
      }
    }
  }
}