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集成
注意：目前只有 支持社区节点。n8n云版本中没有MCP服务器的选项（还没有？）。
安装
- 安装n8n节点mcp包：
npm install n8n-nodes-mcp- 配置n8n以使用自定义节点：
将以下内容添加到n8n配置中：
N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"- 在n8n中配置MCP节点：
- 将“MCP”节点添加到工作流中 - 配置它以连接到您的SurrealDB MCP服务器 - 选择所需的操作（查询、选择、创建等） - 配置操作参数
有关更多详细信息，请访问 .
许可证
麻省理工学院