Couchbase MCP Server (TypeScript/Bun Version)

Couchbase MCP 服务（TypeScript/Bun 版本）

这是一个 MCP 服务实现，可让大模型直接与 Couchbase 集群交互。

功能

工具

数据库操作

• get_scopes_and_collections：列出指定存储桶中的所有作用域和集合
• get_schema_for_collection：获取特定集合的结构和架构
• get_document_by_id：从指定作用域和集合中按 ID 检索文档
• upsert_document_by_id：在指定作用域和集合中按 ID 创建或更新文档
• delete_document_by_id：从指定作用域和集合中按 ID 删除文档
• run_sql_plus_plus_query：在指定作用域上执行 SQL++ 查询

查询分析

• get_detailed_indexes：获取数据库索引的全面信息
• get_detailed_prepared_statements：查看预处理语句的详细信息
• get_system_vitals：监控系统运行状况指标
• get_system_nodes：查看集群节点信息
• get_most_expensive_queries：识别资源消耗最高的查询
• suggest_query_optimizations：获取提升查询性能的建议
• analyze_document_structure：分析并了解文档结构模式
• get_document_type_examples：查看不同类型的示例文档
• get_prepared_statements：列出所有预处理语句
• get_indexes_to_drop：识别未使用或冗余的索引
• get_completed_requests：查看已完成的查询请求
• get_system_indexes：列出所有系统索引
• get_primary_index_queries：识别使用主索引的查询
• get_largest_result_count_queries：查找返回结果数量最多的查询
• get_largest_result_size_queries：识别结果集最大的查询
• get_most_frequent_queries：查看最常执行的查询
• get_longest_running_queries：识别执行时间最长的查询
• get_fatal_requests：查看失败的查询请求

文档管理

• list_documentation：列出 MCP 服务工具和功能的可用文档
• read_documentation：阅读特定文档条目
• create_documentation：为工具和功能创建新的文档条目
• delete_documentation：删除文档条目
• sync_documentation：同步并更新现有文档

操作手册管理

• list_playbooks：列出可用的数据库操作手册

资源

• 数据库结构资源：访问和管理数据库结构信息
• 架构资源：处理集合架构和验证
• 文档资源：管理文档操作和 CRUD 功能
• 查询资源：处理 SQL++ 查询操作和结果
• 查询分析资源：监控并优化查询性能
• 文档资源：管理工具和功能文档
• 操作手册资源：管理并执行数据库操作手册

安全功能

• READ_ONLY_QUERY_MODE：默认启用，防止 SQL++ 查询修改数据
• 通过基于 ID 的访问安全地执行文档操作
• 基于环境配置敏感凭据

前提条件

• Bun 1.0 或更高版本
• 一个正在运行的 Couchbase 集群。最简单的入门方式是使用 Capella 免费层，它是完全托管的 Couchbase Server 版本。你可以按照说明导入一个示例数据集，也可以导入自己的数据集。
• 安装一个 MCP 客户端，例如 Claude Desktop，以将服务连接到 Claude。本文提供了 Claude Desktop 和 Cursor 的说明。也可以使用其他 MCP 客户端。

配置

将仓库克隆到本地计算机。

git clone https://github.com/yourusername/mcp-server-couchbase-bun.git
cd mcp-server-couchbase-bun

安装依赖项：

bun install

构建 TypeScript 项目：

bun run build

根据示例创建 .env 文件：

cp .env.example .env
# Edit .env with your Couchbase credentials

MCP 客户端的服务配置

以下是 Claude Desktop、Cursor、Windsurf Editor 等 MCP 客户端的配置。

{
  "mcpServers": {
    "couchbase-capella-mcp": {
      "command": "bun",
      "args": [
        "/path/to/your/mcp-server-couchbase/dist/index.js",
        "--transport",
        "stdio"
      ],
      "env": {
        "COUCHBASE_URL": "couchbases://your-cluster-url",
        "COUCHBASE_USERNAME": "your-username",
        "COUCHBASE_PASSWORD": "your-password",
        "COUCHBASE_BUCKET": "your-bucket",
        "COUCHBASE_SCOPE": "your-scope",
        "COUCHBASE_COLLECTION": "your-collection",
        "LOG_LEVEL": "debug",
        "DOCS_ENABLED": "true",
        "DOCS_BASE_DIR": "/path/to/your/mcp-server-couchbase/docs",
        "DOCS_FILE_EXT": ".md",
        "PWD": "/path/to/your/mcp-server-couchbase",
        "PATH": "/Users/your-username/.bun/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      },
      "cwd": "/path/to/your/mcp-server-couchbase"
    }
  }
}

注意：将所有 /path/to/your/mcp-server-couchbase 替换为克隆仓库的实际路径。此外，请使用你的 Couchbase 集群详情更新环境变量。

可以使用环境变量配置服务。支持以下变量：

Couchbase 连接设置

• COUCHBASE_URL：Couchbase 集群的连接字符串
• COUCHBASE_USERNAME：用于连接的用户名，需有权访问要使用的存储桶
• COUCHBASE_PASSWORD：用于连接的用户名对应的密码
• COUCHBASE_BUCKET：服务将访问的存储桶名称
• COUCHBASE_SCOPE：要在存储桶中使用的范围
• COUCHBASE_COLLECTION：要在范围中使用的集合
• CN_ROOT：Couchbase 配置的根目录（默认值：'/usr/src'）

MCP 服务设置

• MCP_SERVER_NAME：MCP 服务实例的名称
• MCP_TRANSPORT：要使用的传输模式（stdio 或 sse）
• FASTMCP_PORT：SSE 传输模式的端口号（默认值：8080）
• READ_ONLY_QUERY_MODE：设置是否允许修改数据的 SQL++ 查询（默认值：true）
• LOG_LEVEL：日志级别（例如："debug"、"info"、"warn"、"error"）

文档设置

• DOCS_ENABLED：启用/禁用文档功能
• DOCS_BASE_DIR：文档文件的基础目录
• DOCS_FILE_EXT：文档文件的扩展名

操作手册设置

• PLAYBOOKS_ENABLED：启用/禁用操作手册功能
• PLAYBOOKS_BASE_DIR：操作手册文件的基础目录
• PLAYBOOKS_FILE_EXT：操作手册文件的扩展名

系统设置

• PWD：MCP 服务的工作目录

运行服务

你可以直接运行服务：

# Development mode (TypeScript directly)
bun run dev

# Production mode (compiled JavaScript)
bun run start

使用 SSE 传输模式：

# Development mode (TypeScript directly)
bun run dev:sse

# Production mode (compiled JavaScript)
bun run start:sse

客户端设置说明

Claude Desktop、Cursor 和 Windsurf Editor 的设置说明与原始 Python 版本相同，只需将命令调整为使用 bun 而不是 uv。

SSE 服务模式

可以选择以 Server-Sent Events (SSE) 传输模式运行 MCP 服务。

用法

默认情况下，MCP 服务将在端口 8080 上运行，但可以使用 FASTMCP_PORT 环境变量进行配置。

bun run dist/mcp_server.js --connection-string='<couchbase_connection_string>' --username='<database_username>' --password='<database_password>' --bucket-name='<couchbase_bucket_to_use>' --read-only-query-mode=true --transport=sse

服务将在 http://localhost:8080/sse 上提供。支持 SSE 传输模式的 MCP 客户端可以使用该地址。

与大模型相关的风险

• 使用大模型及类似技术涉及风险，包括可能产生不准确或有害的输出。
• Couchbase 不会审核或评估此类输出的质量或准确性，且此类输出可能不代表 Couchbase 的观点。
• 您应自行决定是否使用大模型及相关技术，并负责遵守适用于您使用这些技术的任何许可条款、使用条款和组织政策。

TypeScript 实现说明

与原始 Python 版本相比，此实现具有以下优势：

1. 类型安全：为所有函数、参数和返回值提供强类型
2. 开发者体验：提供更好的 IDE 支持，包括自动补全和内联文档
3. 性能：Bun 运行时为 JavaScript/TypeScript 应用提供出色的性能

故障排除提示

• 确保配置中的 MCP 服务仓库路径正确。
• 确认 Couchbase 连接字符串、数据库用户名、密码和存储桶名称正确。
• 如果使用 Couchbase Capella，请确保运行 MCP 服务的计算机可以访问集群。
• 检查数据库用户是否拥有访问指定存储桶的适当权限。
• 确认已正确安装 Bun，且可以正常访问。
• 检查日志中是否有可能表明 MCP 服务存在问题的错误或警告。

---

支持政策

我们由衷感谢您对这个项目的关注！ 本项目由社区维护，这意味着没有支持团队提供官方支持。

如果您需要帮助、发现了错误，或希望贡献改进，最好的方式就是在此处提交 GitHub 问题。 我们的支持门户无法协助处理与本项目相关的请求，因此恳请您通过 GitHub 提交所有咨询。

感谢您的协作，帮助我们携手前进！