AI导哈

数据库操作服务器

Couchbase MCP Server是一个基于TypeScript/Bun的服务器实现，允许大型语言模型直接与Couchbase集群交互，提供数据库操作、查询分析和文档管理等功能。

  • by zx8086
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 zx8086/mcp-server-couchbase

使用说明

Couchbase MCP服务器（Types/Bun版本）

一 主控程序 Couchbase的服务器实现，允许LLM直接与Couchbase集群交互。

特性

工具

数据库操作

  • get_scopes_and_collections：列出指定bucket中的所有作用域和集合
  • 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的访问保护文档操作
  • 敏感凭据的基于环境的配置

先决条件

  • 包子 1.0或更高
  • 正在运行的Couchbase集群。最简单的入门方法是使用 卡佩拉 免费层，这是Couchbase服务器的完全托管版本。你可以跟随 说明 导入其中一个示例数据集或导入您自己的数据集。
  • 一 MCP客户端 例如 克劳德桌面 安装以将服务器连接到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客户端的服务器配置

这是MCP客户端的配置，如Claude Desktop、Cursor、Windsurf Editor。

{
  "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_URL：Couchbase集群的连接字符串
  • COUCHBASE_USERNAME：可以访问bucket进行连接的用户名
  • COUCHBASE_PASSWORD：要连接的用户名的密码
  • COUCHBASE_BUCKET：服务器将访问的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：日志记录级别（例如，“调试”、“信息”、“警告”、“错误”）

文档设置

  • 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服务器模式

有一个选项可以在中运行MCP服务器 服务器发送事件（SSE） 运输方式。

用法

默认情况下，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客户端。

与LLM相关的风险

  • 使用大型语言模型和类似技术涉及风险，包括可能产生不准确或有害的输出。
  • Couchbase不审查或评估此类输出的质量或准确性，此类输出可能不反映Couchbase的观点。
  • 您全权负责决定是否使用大型语言模型和相关技术，并遵守任何许可条款、使用条款以及贵组织管理您使用这些模型和技术的政策。

TypeScript实现说明

与原始Python版本相比，此实现具有几个优点：

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

故障排除提示

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

支持政策

我们衷心感谢您对这个项目的兴趣！ 这个项目是 社区维护，这意味着 未得到官方支持 由一个支持团队。

如果你需要帮助，发现了一个bug，或者想做出改进，最好的地方就是这里——通过 打开GitHub问题. 我们的支持门户无法协助处理与此项目相关的请求，因此我们恳请所有查询都留在GitHub上。

您的合作帮助我们共同前进——谢谢！

相关 MCP