星战科技xingzhan.cloud
返回市场
超现实数据库MCP服务器

超现实数据库MCP服务器

作者：nsxdavid32 星标更新：2025-07-16
安装使用来源：spider==github.com

项目介绍

SurrealDB MCP Server

<p align="center"> <img src="assets/images/sdblogo.png" width="256" alt="SurrealDB MCP Server Logo" /> </p> <p align="center"> <a href="https://www.npmjs.com/package/surrealdb-mcp-server"><img src="https://img.shields.io/npm/v/surrealdb-mcp-server.svg" alt="npm 版本"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="许可证：MIT"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js 版本"></a> <a href="https://github.com/modelcontextprotocol/typescript-sdk"><img src="https://img.shields.io/badge/MCP%20SDK-%5E1.6.1-orange" alt="MCP SDK"></a> </p>

这是一个实现了模型上下文协议（MCP）的服务器，它提供了一个标准化接口，使AI助手能够与SurrealDB数据库进行交互。此服务器允许AI系统查询并操作配置好的SurrealDB实例中的数据。

AI助手注意： 如果您是AI助手（如Claude、Cline、Copilot等），阅读此文档，请参阅llms-install.md文件，其中包含了专门为您设计的详细安装和配置指南，以帮助用户安装和配置此MCP服务器。

安装指南

您正在使用的AI助手是什么？

关键术语

  • MCP服务器：实现模型上下文协议的服务器，允许AI助手访问外部工具和资源。
  • MCP主机：连接到MCP服务器的应用程序（如带有Cline或Claude桌面的VS Code）。
  • SurrealDB：一种具有实时能力的可扩展分布式文档图数据库。

可用工具

该服务器提供了以下工具用于与SurrealDB交互：

  • query：执行原始SurrealQL查询。
  • select：从表中选择记录（全部或特定ID）。
  • create：在表中创建一个新记录。
  • update：更新特定记录，替换其内容。
  • delete：通过ID删除特定记录。
  • merge：将数据合并到特定记录中（部分更新）。
  • patch：对特定记录应用JSON Patch操作。
  • upsert：如果不存在则创建记录，否则更新记录。
  • insert：向表中插入多条记录。
  • insertRelation：在两个记录之间创建图形关系（边）。

(请参阅MCP主机的工具列表以获取详细的输入模式。)

📝 Cline安装

Cline VS Code扩展的一键安装

  1. 全局安装包：

    npm install -g surrealdb-mcp-server

  2. 添加到Cline设置：

    编辑位于：%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json 的文件

    添加以下配置：

    {
  "mcpServers": {
    "surrealdb": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\surrealdb-mcp-server\\build\\index.js"
      ],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "your_namespace",
        "SURREALDB_DB": "your_database",
        "SURREALDB_USER": "your_db_user",
        "SURREALDB_PASS": "your_db_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

    重要提示： 将路径中的 YOUR_USERNAME 替换为您的实际Windows用户名。

  3. 重启VS Code

  4. 验证安装：

    • 在VS Code中打开Cline
    • 让Cline“列出可用的MCP服务器”
    • 您应该看到列表中有“surrealdb”

🖥️ Claude安装

Claude桌面应用的安装

  1. 配置Claude桌面以使用服务器：

    编辑Claude桌面应用的MCP设置文件：

    • Windows：%APPDATA%\Claude\claude_desktop_config.json
    • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux：~/.config/Claude/claude_desktop_config.json

    添加以下配置：

    {
  "mcpServers": {
    "surrealdb": {
      "command": "npx",
      "args": [
        "-y",
        "surrealdb-mcp-server"
      ],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "your_namespace",
        "SURREALDB_DB": "your_database",
        "SURREALDB_USER": "your_db_user",
        "SURREALDB_PASS": "your_db_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

    注意： 如上所示使用npx命令意味着MCP客户端将在需要时自动下载并运行npm上的包。无需手动安装。

  2. 重启Claude桌面应用

  3. 验证安装：

    • 让Claude“列出可用的MCP服务器”
    • 您应该看到列表中有“surrealdb”

🤖 Copilot安装

VS Code中的GitHub Copilot安装

  1. 创建工作区配置文件：

    在您的工作区中创建一个文件：.vscode/mcp.json

    添加以下配置：

    {
  "inputs": [
    {
      "type": "promptString",
      "id": "surrealdb-url",
      "description": "SurrealDB URL",
      "default": "ws://localhost:8000"
    },
    {
      "type": "promptString",
      "id": "surrealdb-ns",
      "description": "SurrealDB 命名空间"
    },
    {
      "type": "promptString",
      "id": "surrealdb-db",
      "description": "SurrealDB 数据库"
    },
    {
      "type": "promptString",
      "id": "surrealdb-user",
      "description": "SurrealDB 用户名"
    },
    {
      "type": "promptString",
      "id": "surrealdb-pass",
      "description": "SurrealDB 密码",
      "password": true
    }
  ],
  "servers": {
    "surrealdb": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "surrealdb-mcp-server"
      ],
      "env": {
        "SURREALDB_URL": "${input:surrealdb-url}",
        "SURREALDB_NS": "${input:surrealdb-ns}",
        "SURREALDB_DB": "${input:surrealdb-db}",
        "SURREALDB_USER": "${input:surrealdb-user}",
        "SURREALDB_PASS": "${input:surrealdb-pass}"
      }
    }
  }
}

    注意： 此配置使用VS Code的输入变量来安全地提示并存储您的SurrealDB凭据。

  2. 验证安装：

    • 在VS Code中打开GitHub Copilot聊天
    • 从下拉菜单中选择“代理”模式
    • 点击“工具”按钮查看可用工具
    • 您应该看到列表中有SurrealDB工具

🦘 Roo Code安装

VS Code中的Roo Code安装

  1. 访问MCP设置：

    点击Roo Code面板顶部导航栏中的MCP图标，然后选择“编辑MCP设置”以打开配置文件。

  2. 添加SurrealDB MCP服务器配置：

    {
  "mcpServers": {
    "surrealdb": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\surrealdb-mcp-server\\build\\index.js"
      ],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "your_namespace",
        "SURREALDB_DB": "your_database",
        "SURREALDB_USER": "your_db_user",
        "SURREALDB_PASS": "your_db_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

    重要提示： 将路径中的 YOUR_USERNAME 替换为您的实际Windows用户名。

  3. 重启VS Code

  4. 验证安装：

    • 在VS Code中打开Roo Code
    • 点击MCP图标查看可用服务器
    • 您应该看到列表中有“surrealdb”

🌊 Windsurf安装

Windsurf的安装

  1. 全局安装包：

    npm install -g surrealdb-mcp-server

  2. 配置Windsurf：

    • 在您的系统上打开Windsurf
    • 导航到设置页面
    • 转到Cascade标签页
    • 找到模型上下文协议（MCP）服务器部分
    • 点击“查看原始配置”以打开配置文件（通常位于 ~/.codeium/windsurf/mcp_config.json）

  3. 添加SurrealDB MCP服务器配置：

    {
  "servers": [
    {
      "name": "surrealdb",
      "command": "node",
      "args": [
        "/path/to/global/node_modules/surrealdb-mcp-server/build/index.js"
      ],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "your_namespace",
        "SURREALDB_DB": "your_database",
        "SURREALDB_USER": "your_db_user",
        "SURREALDB_PASS": "your_db_password"
      }
    }
  ]
}

    注意： 将 /path/to/global/node_modules 替换为您的实际全局node_modules目录路径。

  4. 重启Windsurf

  5. 验证安装：

    • 在Windsurf中打开Cascade
    • 您应该看到工具列表中有SurrealDB工具

⚡ Cursor安装

Cursor的安装

  1. 全局安装包：

    npm install -g surrealdb-mcp-server

  2. 配置Cursor：

    • 打开Cursor
    • 转到设置 > Cursor设置
    • 找到MCP服务器选项并启用它
    • 点击“添加新的MCP服务器”

  3. 添加SurrealDB MCP服务器配置：

    {
  "name": "surrealdb",
  "command": "node",
  "args": [
    "/path/to/global/node_modules/surrealdb-mcp-server/build/index.js"
  ],
  "env": {
    "SURREALDB_URL": "ws://localhost:8000",
    "SURREALDB_NS": "your_namespace",
    "SURREALDB_DB": "your_database",
    "SURREALDB_USER": "your_db_user",
    "SURREALDB_PASS": "your_db_password"
  }
}

    注意： 将 /path/to/global/node_modules 替换为您的实际全局node_modules目录路径。

  4. 重启Cursor

  5. 验证安装：

    • 打开Cursor聊天
    • 您应该看到工具列表中有SurrealDB工具

必要的环境变量

此服务器需要以下环境变量以连接到您的SurrealDB实例：

  • SURREALDB_URL：您的SurrealDB实例的WebSocket端点（例如，ws://localhost:8000 或 wss://cloud.surrealdb.com）。
  • SURREALDB_NS：目标命名空间。
  • SURREALDB_DB：目标数据库。
  • SURREALDB_USER：身份验证的用户名（根、命名空间、数据库或作用域用户）。
  • SURREALDB_PASS：指定用户的密码。

故障排除

常见问题

“无法找到模块”错误

如果您看到类似“无法找到模块'surrealdb-mcp-server'”的错误，请尝试：

  1. 验证全局安装：npm list -g surrealdb-mcp-server
  2. 检查配置中的路径是否与实际安装路径匹配
  3. 尝试重新安装：npm install -g surrealdb-mcp-server

连接错误

如果您看到“连接到SurrealDB失败”：

  1. 验证SurrealDB是否正在运行：surreal start --log debug
  2. 检查您的连接URL、命名空间、数据库和凭据
  3. 确保您的SurrealDB实例可以从指定路径访问

Cline特定问题

如果使用npx方法在Cline上不起作用：

  1. 对于Cline始终使用全局安装方法
  2. 指定node.exe和已安装包的完整路径
  3. 确保将YOUR_USERNAME替换为您的实际Windows用户名

高级配置

使用本地构建

如果您已经克隆了仓库或想要使用本地构建，可以使用以下配置：

{
  "mcpServers": {
    "surrealdb": {
      "command": "node",
      "args": ["/path/to/your/surrealdb-mcp-server/build/index.js"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "your_namespace",
        "SURREALDB_DB": "your_database",
        "SURREALDB_USER": "your_db_user",
        "SURREALDB_PASS": "your_db_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
  • 将 /path/to/your/surrealdb-mcp-server 替换为您实际克隆仓库的位置
  • 将环境变量值替换为您的实际SurrealDB连接详情

开发

如果您想为此MCP服务器贡献开发，请遵循以下步骤：

本地开发设置

  1. 克隆仓库：

    git clone https://github.com/nsxdavid/surrealdb-mcp-server.git
cd surrealdb-mcp-server

  2. 安装依赖项：

    npm install

  3. 构建项目：

    npm run build

本地运行

# 确保设置了所需的SURREALDB_*环境变量
npm run dev # （注意：dev脚本使用ts-node直接运行TypeScript）
# 或运行构建版本：
npm start

测试

npm test # （注意：测试需要实现）

贡献

欢迎贡献！请参阅CONTRIBUTING.md以获取指南。

与n8n集成

您可以使用n8n-nodes-mcp社区节点将此SurrealDB MCP服务器与n8n集成。

注意：目前只有n8n自托管（Docker）版本支持社区节点。n8n云版本（暂时）没有MCP服务器选项。

安装

  1. 安装n8n-nodes-mcp包：

    npm install n8n-nodes-mcp

  2. 配置n8n以使用自定义节点：

    在您的n8n配置中添加以下内容：

    N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"

  3. 在n8n中配置MCP节点：

    • 向您的工作流添加“MCP”节点
    • 配置它以连接到您的SurrealDB MCP服务器
    • 选择所需的操作（查询、选择、创建等）
    • 配置操作参数

更多细节，请访问n8n-nodes-mcp GitHub仓库。

许可证

MIT