SurrealDB MCP Server

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 扩展的一键安装

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 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 下载并运行软件包。无需手动安装。

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 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 凭据。

2. 验证安装：
   • 在 VS Code 中打开 GitHub Copilot Chat
   • 从下拉菜单中选择“代理”模式
   • 点击“工具”按钮查看可用工具
   • 您应该在列表中看到 SurrealDB 工具

🦘 Roo 代码安装

在 VS Code 中安装 Roo Code

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

🌊 风帆冲浪安装

风帆冲浪安装

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. 重启风帆冲浪
5. 验证安装：
   • 在风帆冲浪中打开 Cascade
   • 您应该在工具列表中看到可用的 SurrealDB 工具

⚡ 光标安装

Cursor 的安装

1. 全局安装包：
   npm install -g surrealdb-mcp-server
2. 配置光标：
   • 打开游标
   • 前往“设置”>“光标设置”
   • 找到 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. 重启光标
5. 验证安装：
   • 打开光标聊天
   • 您应该在工具列表中看到可用的 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’”的错误，请尝试：

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 实例可以从指定的路径访问

克莱恩特有的问题

如果 npx 方法不适用于 Cline：

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

高级配置

使用本地构建

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

• 将/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

本地运行

测试

贡献

欢迎贡献！请参阅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 存储库。

执照

麻省理工学院