SurrealDB MCP 服务器

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

**人工智能助手注意事项：**如果您是阅读本文档的人工智能助手（如 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 主机：连接到 MCP 服务器的应用程序（例如带有 Cline 或 Claude Desktop 的 VS Code）
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 桌面应用程序的安装

配置 Claude Desktop 以使用服务器：编辑 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 下载并运行软件包。无需手动安装。
重启 Claude 桌面应用程序
验证安装：
- 要求 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
- 从下拉菜单中选择“代理”模式
- 点击“工具”按钮查看可用工具
- 您应该在列表中看到 SurrealDB 工具

🦘 Roo 代码安装

在 VS Code 中安装 Roo Code

访问 MCP 设置：单击 Roo 代码窗格顶部导航中的 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”

🌊 风帆冲浪安装

风帆冲浪安装

全局安装包：
npm install -g surrealdb-mcp-server
配置 Windsurf：
- 在您的系统上打开 Windsurf
- 导航至“设置”页面
- 转到“Cascade”选项卡
- 查找模型上下文协议 (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 目录的实际路径。
重启风帆冲浪
验证安装：
- 在风帆冲浪中打开 Cascade
- 您应该在工具列表中看到可用的 SurrealDB 工具

⚡ 光标安装

Cursor 的安装

全局安装包：
npm install -g surrealdb-mcp-server
配置光标：
- 打开游标
- 前往“设置”>“光标设置”
- 找到 MCP 服务器选项并启用它
- 点击“添加新的 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 目录的实际路径。
重启光标
验证安装：
- 打开光标聊天
- 您应该在工具列表中看到可用的 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 ：指定用户的密码。

故障排除

常见问题

“找不到模块”错误

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

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

连接错误

如果您看到“无法连接到 SurrealDB”：

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

克莱恩特有的问题

如果 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 服务器与n8n集成。

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

安装

安装 n8n-nodes-mcp 包：
npm install n8n-nodes-mcp
配置 n8n 以使用自定义节点：将以下内容添加到您的 n8n 配置：
N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"
在 n8n 中配置 MCP 节点：
- 将“MCP”节点添加到您的工作流程中
- 配置它以连接到您的 SurrealDB MCP 服务器
- 选择所需的操作（查询、选择、创建等）
- 配置运行参数

有关更多详细信息，请访问n8n-nodes-mcp GitHub 存储库。

执照

麻省理工学院

SurrealDB MCP Server