使用说明

SurealDB MCP服务器

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

人工智能助理注意事项： 如果您是阅读本文档的人工智能助理（如Claude、Cline、Copilot等），请参阅 llms-install.md 文件中提供了专门为您设计的详细说明，以帮助用户安装和配置此MCP服务器。

安装指南

你正在使用哪种人工智能助手？

📝 使用Cline VS代码扩展？ → 转到Cline安装
🖥️ 使用克劳德桌面应用程序？ → 转到Claude安装
🤖 在VS代码中使用GitHub Copilot？ → 转到副驾驶安装
🦘 在VS代码中使用Roo代码？ → 转到Roo代码安装
🌊 使用Windsurf？ → 转到Windsurf安装
⚡ 使用光标？ → 转到游标安装
🔄 使用 n8n? → 转到n8n集成

关键术语

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

可用工具

服务器公开了以下与SurrealDB交互的工具：

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

（有关详细的输入模式，请参阅MCP主机的工具列表。）

📝 Cline安装

Cline VS代码扩展的一键安装

全局安装软件包：
```
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代码
验证安装：
- 在VS代码中打开Cline
- 要求Cline“列出可用的MCP服务器”
- 你应该在列表中看到“surraldb”

🖥️ 克劳德安装

Claude桌面应用程序的安装

配置Claude Desktop以使用服务器：

编辑Claude Desktop App的MCP设置文件：

窗户： %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“列出可用的MCP服务器”
- 你应该在列表中看到“surraldb”

🤖 副驾驶安装

在VS代码中安装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代码中打开GitHub Copilot聊天
- 从下拉菜单中选择“代理”模式
- 点击“工具”按钮查看可用工具
- 您应该在列表中看到SurrealDB工具

🦘 Roo代码安装

在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代码
验证安装：
- 在VS Code中打开Roo Code
- 单击MCP图标查看可用服务器
- 你应该在列表中看到“surraldb”

🌊 风帆安装

风帆安装

全局安装软件包：
```
npm install -g surrealdb-mcp-server
```
配置Windsurf：
- 在您的系统上打开Windsurf
- 导航到“设置”页面
- 转到“级联”选项卡
- 查找模型上下文协议（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
验证安装：
- 风浪中的开放瀑布
- 您应该在工具列表中看到可用的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或作用域用户）。
SURREALDB_PASS：指定用户的密码。

故障排除

常见问题

“找不到模块”错误

如果您看到类似“找不到模块'surraldb-mcp服务器'”的错误，请尝试：

验证全局安装： 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)

贡献

欢迎投稿！请看贡献.md 作为指导方针。

与n8n集成

您可以将此SurealDB MCP服务器与 n8n 使用 n8n节点mcp 社区节点。

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

安装

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

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

有关更多详细信息，请访问 n8n节点mcp GitHub存储库.

许可证

麻省理工学院

使用说明

SurealDB MCP服务器

安装指南

你正在使用哪种人工智能助手？

关键术语

可用工具

📝 Cline安装

Cline VS代码扩展的一键安装

🖥️ 克劳德安装

Claude桌面应用程序的安装

🤖 副驾驶安装

在VS代码中安装GitHub Copilot

🦘 Roo代码安装

在VS Code中安装Roo Code

🌊 风帆安装

风帆安装

⚡ 光标安装

Cursor的安装

所需的环境变量

故障排除

常见问题

“找不到模块”错误

连接错误

临床具体问题

高级配置

使用本地构建

发展

地方发展设置

本地运行

测试

贡献

与n8n集成

安装

许可证

相关 MCP

ChatGPT交互工具

Loki日志查询服务

JSON数据查询与操作服务器

Genkit MCP 集成插件

WHOIS查询服务

运行时参数注入工具