SurrealDB MCP Server

Name: SurrealDB MCP Server
Author: nsxdavid

本地服务

github.com/nsxdavid数据库3967 周前更新

代码仓库

关于 SurrealDB MCP Server

SurrealDB MCP Server 是一个 MCP 服务，让 AI 助手通过标准接口查询和修改 SurrealDB 数据库。它面向需要用自然语言操作 SurrealDB 数据的用户，并提供多种 MCP 客户端的安装说明。

主要功能

01执行原始 SurrealQL 查询
02记录的增删改查与局部更新
03JSON Patch 与 upsert 操作
04批量插入与图关系（边）创建
05通过环境变量配置连接参数

适用场景

01让 AI 助手读取或修改 SurrealDB 中的记录
02在 Cline、Claude Desktop 或 Cursor 中接入 SurrealDB
03通过 n8n 工作流调用 SurrealDB 数据

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 SurrealDB 的查询与记录操作工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "surrealdb": {
      "command": "npx",
      "args": [
        "-y",
        "surrealdb-mcp-server"
      ],
      "env": {
        "SURREALDB_URL": "<SURREALDB_URL>",
        "SURREALDB_NS": "<SURREALDB_NS>",
        "SURREALDB_DB": "<SURREALDB_DB>",
        "SURREALDB_USER": "<SURREALDB_USER>",
        "SURREALDB_PASS": "<SURREALDB_PASS>"
      }
    }
  }
}

启动命令npx -y surrealdb-mcp-server

需要配置的环境变量

SURREALDB_URL

SURREALDB_NS

SURREALDB_DB

SURREALDB_USER

SURREALDB_PASS

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmsurrealdb-mcp-serverstdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

SurrealDB MCP 服务

SurrealDB MCP 服务 Logo

一个模型上下文协议（MCP）服务，为 AI 助手提供与 SurrealDB 数据库交互的标准化接口。此服务使 AI 系统能够查询和操作已配置的 SurrealDB 实例中的数据。

给 AI 助手的说明： 如果你是正在阅读本文档的 AI 助手（如 Claude、Cline、Copilot 等），请参阅 llms-install.md 文件，其中提供了专为你设计的详细说明，可帮助用户安装和配置此 MCP 服务。

安装指南

你正在使用哪个 AI 助手？

📝 使用 Cline VS Code 扩展？ → 前往 Cline 安装说明
🖥️ 使用 Claude 桌面应用？ → 前往 Claude 安装说明
🤖 在 VS Code 中使用 GitHub Copilot？ → 前往 Copilot 安装说明
🦘 在 VS Code 中使用 Roo Code？ → 前往 Roo Code 安装说明
🌊 使用 Windsurf？ → 前往 Windsurf 安装说明
⚡ 使用 Cursor？ → 前往 Cursor 安装说明
🔄 使用 n8n？ → 前往 n8n 集成

关键术语

MCP 服务：实现模型上下文协议的服务，使 AI 助手能够访问外部工具和资源
MCP Host：连接到 MCP 服务的应用程序（如配备 Cline 的 VS Code 或 Claude Desktop）
SurrealDB：具备实时功能的可扩展分布式文档图数据库

可用工具

此服务提供以下工具，用于与 SurrealDB 交互：

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

（详细的输入架构请参阅 MCP 主机的工具列表。）

📝 Cline 安装

一键安装 Cline VS Code 扩展

全局安装软件包：
```
npm install -g surrealdb-mcp-server
```

添加到 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 用户名。

重启 VS Code
验证安装：
- 在 VS Code 中打开 Cline
- 让 Cline“列出可用的 MCP 服务”
- 你应该会在列表中看到“surrealdb”

🖥️ Claude 安装

Claude Desktop App 安装

配置 Claude Desktop 以使用该服务：

编辑 Claude Desktop App 的 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 下载并运行该软件包。无需手动安装。

重启 Claude Desktop App
验证安装：
- 请 Claude“列出可用的 MCP 服务”
- 你应该会在列表中看到“surrealdb”

🤖 Copilot 安装

在 VS Code 中安装 GitHub Copilot

创建工作区配置文件：

在工作区中创建文件：.vscode/mcp.json

添加以下配置：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "surrealdb-url",
      "description": "SurrealDB URL",
      "default": "ws://localhost:8000"
    },
    {
      "type": "promptString",
      "id": "surrealdb-ns",
      "description": "SurrealDB Namespace"
    },
    {
      "type": "promptString",
      "id": "surrealdb-db",
      "description": "SurrealDB Database"
    },
    {
      "type": "promptString",
      "id": "surrealdb-user",
      "description": "SurrealDB Username"
    },
    {
      "type": "promptString",
      "id": "surrealdb-pass",
      "description": "SurrealDB Password",
      "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 凭据。

验证安装：
- 在 VS Code 中打开 GitHub Copilot Chat
- 从下拉菜单中选择“Agent”模式
- 点击“工具”按钮，查看可用工具
- 你应该会在列表中看到 SurrealDB 工具

🦘 Roo Code 安装

在 VS Code 中安装 Roo Code

打开 MCP 设置：

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

添加 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 用户名。

重启 VS Code
验证安装：
- 在 VS Code 中打开 Roo Code
- 点击 MCP 图标查看可用服务
- 你应该会在列表中看到“surrealdb”

🌊 Windsurf 安装

安装 Windsurf

全局安装软件包：
```
npm install -g surrealdb-mcp-server
```
配置 Windsurf：
- 在系统中打开 Windsurf
- 前往设置页面
- 打开 Cascade 选项卡
- 找到 Model Context Protocol (MCP) 服务部分
- 点击“查看原始配置”以打开配置文件（通常位于 ~/.codeium/windsurf/mcp_config.json）

添加 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 目录的实际路径。

重启 Windsurf
验证安装：
- 在 Windsurf 中打开 Cascade
- 你应该会在工具列表中看到可用的 SurrealDB 工具

⚡ Cursor 安装

安装 Cursor

全局安装软件包：
```
npm install -g surrealdb-mcp-server
```
配置 Cursor：
- 打开 Cursor
- 前往 Settings > Cursor Settings
- 找到 MCP Servers 选项并启用
- 点击“添加新的 MCP 服务”

添加 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 目录的实际路径。

重启 Cursor
验证安装：
- 打开 Cursor Chat
- 你应该会在工具列表中看到可用的 SurrealDB 工具

必需的环境变量

此服务需要以下环境变量才能连接到你的 SurrealDB 实例：

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

故障排除

常见问题

“Cannot find module” 错误

如果看到类似 “Cannot find module 'surrealdb-mcp-server'” 的错误，请尝试：

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

连接错误

如果看到 “Failed to connect to SurrealDB”，请：

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

Cline 特定问题

如果 npx 方式无法与 Cline 配合使用：

对于 Cline，请始终使用全局安装方式
指定 node.exe 和已安装软件包的完整路径
确保将 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 服务的开发，请按照以下步骤操作：

本地开发环境设置

克隆仓库：

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

安装依赖：
```
npm install
```
构建项目：
```
npm run build
```

本地运行

# Ensure required SURREALDB_* environment variables are set
npm run dev # (Note: dev script uses ts-node to run TypeScript directly)
# Or run the built version:
npm start

测试

npm test # (Note: Tests need to be implemented)

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

与 n8n 集成

你可以使用社区节点 n8n-nodes-mcp，将此 SurrealDB MCP Server 与 n8n 集成。

注意：目前只有 n8n 的可自托管（Docker）版本支持社区节点。n8n 云版本目前还没有提供 MCP Servers 选项（？）。

安装

安装 n8n-nodes-mcp 软件包：
```
npm install n8n-nodes-mcp
```
配置 n8n 以使用自定义节点：

将以下内容添加到 n8n 配置中：
```
N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"
```
在 n8n 中配置 MCP 节点：
- 将 “MCP” 节点添加到工作流
- 将其配置为连接到你的 SurrealDB MCP Server
- 选择所需的操作（查询、选择、创建等）
- 配置操作参数

如需了解更多详情，请访问 n8n-nodes-mcp GitHub 仓库。

许可证

MIT

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

SurrealDB MCP Server

关于 SurrealDB MCP Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

SurrealDB MCP 服务

安装指南

你正在使用哪个 AI 助手？

关键术语

可用工具

📝 Cline 安装

一键安装 Cline VS Code 扩展

🖥️ Claude 安装

Claude Desktop App 安装

🤖 Copilot 安装

在 VS Code 中安装 GitHub Copilot

🦘 Roo Code 安装

在 VS Code 中安装 Roo Code

🌊 Windsurf 安装

安装 Windsurf

⚡ Cursor 安装

安装 Cursor

必需的环境变量

故障排除

常见问题

“Cannot find module” 错误

连接错误

Cline 特定问题

高级配置

使用本地构建版本

开发

本地开发环境设置

本地运行

测试

贡献

与 n8n 集成

安装

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？