MCP 服务器

SurrealDB MCP Server

将你的AI模型连接到你最喜欢的SurrealDB数据库，让LLM为你完成所有工作。

nsxdavid

开发者工具

访问服务器

README

SurrealDB MCP 服务器

一个模型上下文协议 (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 主机：连接到 MCP 服务器的应用程序（如带有 Cline 的 VS Code 或 Claude 桌面）
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 桌面以使用服务器：

编辑 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
- 从下拉列表中选择 "Agent" 模式
- 单击 "Tools" 按钮以查看可用工具
- 您应该在列表中看到 SurrealDB 工具

🦘 Roo Code 安装

在 VS Code 中安装 Roo Code

访问 MCP 设置：

单击 Roo Code 窗格顶部导航栏中的 MCP 图标，然后选择 "Edit MCP Settings" 以打开配置文件。

添加 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
- 导航到 Settings 页面
- 转到 Cascade 选项卡
- 找到 Model Context Protocol (MCP) Servers 部分
- 单击 "View raw config" 以打开配置文件（通常位于 ~/.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 选项并启用它
- 单击 "Add New MCP Server"

添加 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 '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
```

本地运行

# 确保已设置必需的 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 服务器的选项（尚未？）。

安装

安装 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 存储库。

许可证

MIT

SurrealDB MCP Server

README

SurrealDB MCP 服务器

安装指南

您正在使用哪个 AI 助手？

关键术语

可用工具

📝 Cline 安装

Cline VS Code 扩展的一键安装

🖥️ Claude 安装

Claude 桌面应用程序的安装

🤖 Copilot 安装

在 VS Code 中安装 GitHub Copilot

🦘 Roo Code 安装

在 VS Code 中安装 Roo Code

🌊 Windsurf 安装

Windsurf 的安装

⚡ Cursor 安装

Cursor 的安装

必需的环境变量

故障排除

常见问题

"找不到模块" 错误

连接错误

Cline 特定问题

高级配置

使用本地构建

开发

本地开发设置

本地运行

测试

贡献

与 n8n 集成

安装

许可证

推荐服务器