STARWARCLOUD STARWAR.AI
返回市场
MCP服务器Couchbase

MCP服务器Couchbase

作者：Couchbase-Ecosystem25 星标更新：2025-11-21
安装使用来源：spider==github.com

项目介绍

Couchbase MCP Server

这是一个Couchbase实现的MCP服务器，允许LLMs直接与Couchbase集群交互。

License Python 3.10+ PyPI version Verified on MseeP Trust Score

<a href="https://glama.ai/mcp/servers/@Couchbase-Ecosystem/mcp-server-couchbase"> <img width="380" height="200" src="https://gips3.baidu.com/it/u=3713411280,2187194665&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Couchbase Server MCP server" /> </a> <!-- mcp-name: io.github.Couchbase-Ecosystem/mcp-server-couchbase -->

功能

  • 获取集群中所有存储桶的列表
  • 获取指定存储桶中的所有范围和集合的列表
  • 获取指定存储桶中的所有范围的列表
  • 获取指定范围和存储桶中的所有集合的列表。请注意，此工具需要集群具有查询服务。
  • 获取集合的结构
  • 根据ID从指定的范围和集合中获取文档
  • 将文档插入到指定的范围和集合中
  • 根据ID从指定的范围和集合中删除文档
  • 在指定的范围内运行SQL++查询
    • 查询会自动作用于指定的存储桶和范围，因此可以直接使用集合名称（例如，使用SELECT * FROM users而不是SELECT * FROM bucket.scope.users）
    • MCP服务器有一个选项CB_MCP_READ_ONLY_QUERY_MODE默认设置为真，以禁用运行更改数据或底层集合结构的SQL++查询。请注意，仍然可以通过ID更新文档。
  • 获取MCP服务器的状态
  • 通过连接到集群来检查集群凭据
  • 列出集群中的所有索引及其定义，可选地按存储桶、范围、集合和索引名称进行过滤。
  • 为给定的SQL++查询获取Couchbase索引顾问的索引建议，以优化查询性能
  • 获取集群健康状态和所有正在运行的服务列表

先决条件

  • Python 3.10或更高版本。
  • 运行中的Couchbase集群。最简单的方法是使用Capella免费层，这是一个完全托管的Couchbase服务器版本。您可以按照说明导入一个示例数据集或导入您自己的数据集。
  • 安装uv以运行服务器。
  • 安装MCP客户端，如Claude Desktop，以将服务器连接到Claude。提供了Claude Desktop和Cursor的说明。也可以使用其他MCP客户端。

配置

MCP服务器可以从预构建的PyPI包或源代码使用uv运行。

从PyPI运行

我们发布了一个预构建的PyPI包用于MCP服务器。

使用预构建包配置MCP客户端的服务器

基本认证

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

或者

mTLS

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

注意：如果您在客户端中有其他MCP服务器在使用，可以将其添加到现有的mcpServers对象中。

从源代码运行

MCP服务器可以从这个仓库的源代码运行。

将仓库克隆到本地机器。

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

使用源代码配置MCP客户端的服务器

这是用于Claude Desktop、Cursor、Windsurf Editor等MCP客户端的通用配置。

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

注意：path/to/cloned/repo/mcp-server-couchbase/应该是您本地机器上克隆的仓库路径。别忘了路径末尾的斜杠！

注意：如果您在客户端中有其他MCP服务器在使用，可以将其添加到现有的mcpServers对象中。

MCP服务器的附加配置

服务器可以通过环境变量或命令行参数进行配置：

环境变量CLI参数描述默认值
CB_CONNECTION_STRING--connection-string连接到Couchbase集群的连接字符串必需
CB_USERNAME--username对所需存储桶具有访问权限的基本身份验证用户名必需（或mTLS需要客户端证书和密钥）
CB_PASSWORD--password基本身份验证密码必需（或mTLS需要客户端证书和密钥）
CB_CLIENT_CERT_PATH--client-cert-pathmTLS身份验证的客户端证书文件路径如果使用mTLS则必需（或需要用户名和密码）
CB_CLIENT_KEY_PATH--client-key-pathmTLS身份验证的客户端密钥文件路径如果使用mTLS则必需（或需要用户名和密码）
CB_CA_CERT_PATH--ca-cert-path如果服务器配置了自签名或不受信任的证书，则用于TLS的服务器根证书路径。如果您连接到Capella，则不需要此证书。
CB_MCP_READ_ONLY_QUERY_MODE--read-only-query-mode防止数据修改查询true
CB_MCP_TRANSPORT--transport传输模式：stdio，http，ssestdio
CB_MCP_HOST--hostHTTP/SSE传输模式的主机127.0.0.1
CB_MCP_PORT--portHTTP/SSE传输模式的端口8000

注意：对于身份验证，您需要提供用户名和密码或客户端证书和密钥路径。可选地，您可以指定用于验证服务器证书的CA根证书路径。 如果同时指定了客户端证书及密钥路径和用户名及密码，则将使用客户端证书进行身份验证。

您还可以使用以下命令检查服务器版本：

uvx couchbase-mcp-server --version

客户端特定配置

<details> <summary>Claude Desktop</summary>

按照以下步骤使用Couchbase MCP服务器与Claude Desktop MCP客户端

  1. 通过编辑配置文件将MCP服务器添加到Claude Desktop。更多详细说明可以在MCP快速入门指南中找到。

    • 在Mac上，配置文件位于~/Library/Application Support/Claude/claude_desktop_config.json
    • 在Windows上，配置文件位于%APPDATA%\Claude\claude_desktop_config.json

    打开配置文件，并将配置添加到mcpServers部分。

  2. 重启Claude Desktop以应用更改。

  3. 您现在可以在Claude Desktop中使用该服务器，使用自然语言对Couchbase集群执行查询并执行文档的CRUD操作。

日志

Claude Desktop的日志可以在以下位置找到：

  • MacOS: ~/Library/Logs/Claude
  • Windows: %APPDATA%\Claude\Logs

这些日志可用于诊断连接问题或其他与您的MCP服务器配置相关的问题。有关更多详细信息，请参阅官方文档。

</details> <details> <summary>Cursor</summary>

按照以下步骤使用Couchbase MCP服务器与Cursor：

  1. 在您的机器上安装Cursor。

  2. 在Cursor中，转到Cursor > Cursor设置 > 工具与集成 > MCP工具。也可以查看Cursor上的设置MCP服务器配置文档。

  3. 指定相同的配置。您可能需要在mcpServers父键下添加服务器配置。

  4. 保存配置。

  5. 您将在MCP服务器列表中看到已添加的couchbase服务器。刷新以查看服务器是否已启用。

  6. 您现在可以在Cursor中使用Couchbase MCP服务器，使用自然语言对Couchbase集群执行查询并执行文档的CRUD操作。

有关MCP与Cursor集成的更多详细信息，请参阅官方Cursor MCP文档。

日志

在Cursor底部面板中，点击“输出”并从下拉菜单中选择“Cursor MCP”以查看服务器日志。这可以帮助诊断连接问题或其他与您的MCP服务器配置相关的问题。

</details> <details> <summary>Windsurf Editor</summary>

按照以下步骤使用Couchbase MCP服务器与Windsurf Editor：

  1. 在您的机器上安装Windsurf Editor。

  2. 在Windsurf Editor中，导航到命令面板 > Windsurf MCP配置面板或Windsurf - 设置 > 高级 > 级联 > 模型上下文协议（MCP）服务器。有关更多配置详情，请参阅官方文档。

  3. 单击添加服务器，然后添加自定义服务器。在编辑器中打开的配置中，添加上面的Couchbase MCP服务器配置。

  4. 保存配置。

  5. 您将在高级设置下的MCP服务器列表中看到已添加的couchbase服务器。刷新以查看服务器是否已启用。

  6. 您现在可以在Windsurf Editor中使用Couchbase MCP服务器，使用自然语言对Couchbase集群执行查询并执行文档的CRUD操作。

有关MCP与Windsurf Editor集成的更多详细信息，请参阅官方Windsurf MCP文档。

</details>

可流式HTTP传输模式

MCP服务器可以在可流式HTTP传输模式下运行，该模式允许多个客户端通过HTTP连接到同一个服务器实例。 在尝试以这种模式连接到MCP服务器之前，请检查您的MCP客户端是否支持可流式HTTP传输。

注意：此模式不包括授权支持。

使用方法

默认情况下，MCP服务器将在端口8000上运行，但可以通过--port或CB_MCP_PORT环境变量进行配置。

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-query-mode=true \
  --transport=http

服务器将在http://localhost:8000/mcp上可用。这可以在支持可流式HTTP传输模式的MCP客户端中使用，例如Cursor。

MCP客户端配置

{
  "mcpServers": {
    "couchbase-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

SSE传输模式

可以选择在服务器发送事件（SSE）传输模式下运行MCP服务器。

注意：SSE模式已被MCP弃用。我们支持可流式HTTP。

使用方法

默认情况下，MCP服务器将在端口8000上运行，但可以通过--port或CB_MCP_PORT环境变量进行配置。

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-query-mode=true \
  --transport=sse

服务器将在http://localhost:8000/sse上可用。这可以在支持SSE传输模式的MCP客户端中使用，例如Cursor。

MCP客户端配置

{
  "mcpServers": {
    "couchbase-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Docker镜像

MCP服务器也可以构建并作为Docker容器运行。预构建的镜像可以在DockerHub上找到。

另外，我们是Docker MCP目录的一部分。

构建镜像

docker build -t mcp/couchbase .
<details> <summary>使用参数构建</summary> 如果您想使用提交哈希和构建时间的构建参数进行构建，可以使用： 
docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mcp/couchbase .

或者，使用提供的构建脚本：

./build.sh

此脚本会自动：

  • 生成git提交哈希和构建时间戳
  • 创建多个有用的标签（latest，<short-commit>）
  • 显示构建信息和结果
  • 使用与CI/CD构建相同的参数

验证镜像标签：

# 查看镜像中的git提交哈希
docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase:latest

# 查看所有元数据标签
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase:latest
</details>

运行

MCP服务器可以使用环境变量配置Couchbase设置。环境变量与配置部分中描述的一致。

独立Docker容器

docker run --rm -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
  -e CB_MCP_READ_ONLY_QUERY_MODE='<true|false>' \
  -e CB_MCP_PORT=9001 \
  -p 9001:9001 \
  mcp/couchbase

CB_MCP_PORT环境变量仅适用于http和sse等HTTP传输模式。

MCP客户端配置

Docker镜像可以在stdio传输模式下使用以下配置。

{
  "mcpServers": {
    "couchbase-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_user>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "mcp/couchbase"
      ]
    }
  }
}

注意事项

  • couchbase_connection_string的值取决于Couchbase服务器是在同一主机机器上运行，还是在另一个Docker容器中，或者在远程主机上运行。如果您的Couchbase服务器在主机机器上运行，那么连接字符串可能是couchbase://host.docker.internal的形式。详情请参阅docker文档。
  • 您可以使用--network=<your_network>选项指定容器的网络。您选择的网络取决于您的环境，默认是bridge。详情请参阅docker网络驱动程序。

大型语言模型相关的风险

  • 使用大型语言模型和技术涉及风险，包括潜在