🚀 SurrealDB MCP 服务器文档
SurrealDB MCP 服务器为用户提供了便捷的方式来集成和管理 SurrealDB 实例，支持多种安装和配置方式，满足不同场景的使用需求。
🚀 快速开始
基本配置示例
以下是 mcp.json 文件的一个基本配置示例：
{
"mcpServers": {
"surrealdb": {
"command": "node",
"args": ["$(npm prefix)/bin/surrealdb-mcp-server"],
"env": {
"SURREALDB_URL": "ws://localhost:8000",
"SURREALDB_NS": "my-namespace",
"SURREALDB_DB": "my-database",
"SURREALDB_USER": "root",
"SURREALDB_PASS": "password"
},
"disabled": false,
"autoApprove": []
}
}
}
配置参数说明
command：指定运行命令的可执行文件路径。args：传递给命令的参数列表。env：设置环境变量以连接到 SurrealDB 实例。disabled：是否禁用此 MCP 服务器（默认为false）。autoApprove：自动批准的操作列表。
✨ 主要特性
- 支持使用 npm 全局安装和 npx 直接运行。
- 可通过
mcp.json文件进行灵活配置。 - 支持批量操作请求和详细的日志记录功能。
📦 安装指南
使用 npm 安装
将 surrealdb-mcp-server 全局安装到您的系统中：
npm install -g surrealdb-mcp-server
使用 npx 运行
无需安装，直接使用 npx 运行：
npx surrealdb-mcp-server
💻 使用示例
基础用法
集成到项目中
在您的项目根目录下创建一个 mcp.json 文件，并根据需要添加多个 MCP 服务器配置。例如：
cd your-project
npm init -y # 如果还没有 package.json
然后在您的代码中引入并使用 MCP 服务器：
const { MCP } = require('surrealdb-mcp-server');
// 或者使用 ES6 模块语法：
import { MCP } from 'surrealdb-mcp-server';
高级用法
创建 MCP 客户端
以下是一个简单的客户端实现示例：
const { createMCPClient } = require('surrealdb-mcp-server');
async function main() {
const client = await createMCPClient({
serverName: 'surrealdb',
command: 'node',
args: ['$(npm prefix)/bin/surrealdb-mcp-server'],
env: {
SURREALDB_URL: 'ws://localhost:8000',
SURREALDB_NS: 'my-namespace',
SURREALDB_DB: 'my-database',
SURREALDB_USER: 'root',
SURREALDB_PASS: 'password'
}
});
// 执行数据库操作
await client.execute('SELECT * FROM users');
}
main().catch(console.error);
📚 详细文档
环境变量配置
以下是需要设置的环境变量及其含义：
| 环境变量名 | 类型 | 必填 | 描述 |
|---|---|---|---|
SURREALDB_URL |
String | 是 | 连接 URL（例如：ws://localhost:8000 或 wss://cloud.surrealdb.com） |
SURREALDB_NS |
String | 是 | 目标 Namespace |
SURREALDB_DB |
String | 是 | 目标 Database |
SURREALDB_USER |
String | 是 | 用户名（Root、NS、DB 或 Scope 用户） |
SURREALDB_PASS |
String | 是 | 密码 |
使用场景
本地开发
在本地项目中使用 MCP 服务器时，可以将其作为开发依赖添加到 package.json：
{
"name": "my-project",
"version": "1.0.0",
"scripts": {
"start": "surrealdb-mcp-server"
},
"devDependencies": {
"surrealdb-mcp-server": "^1.0.0"
}
}
然后运行：
npm install
npm start
生产环境
在生产环境中使用时，建议将 MCP 服务器作为服务运行。例如，在 Linux 系统上可以将其注册为系统服务。
高级配置
批量操作支持
MCP 服务器支持批量操作请求，您可以根据需要扩展功能：
// 在 mcp.json 中添加多个服务器配置
{
"mcpServers": {
"surrealdb1": { ... },
"surrealdb2": { ... }
}
}
日志记录
MCP 服务器支持详细的日志记录功能，您可以自定义日志输出格式和级别：
// 在 mcp.json 中添加日志配置
{
"logging": {
"level": "debug",
"outputFile": "./mcp.log"
}
}
🔧 技术细节
故障排除
"无法找到模块" 错误
如果出现类似 "Cannot find module 'surrealdb-mcp-server'" 的错误，请尝试以下步骤：
- 验证全局安装：
npm list -g surrealdb-mcp-server - 检查配置中的路径是否与实际安装路径匹配
- 重新安装：
npm install -g surrealdb-mcp-server
连接问题
如果出现 "Failed to connect to SurrealDB" 错误，请检查以下内容：
- 确保 SurrealDB 实例正在运行。
- 检查网络连接是否正常。
- 验证环境变量是否正确设置。
其他注意事项
权限问题
在某些系统上，您可能需要以管理员权限运行 MCP 服务器。例如，在 Windows 上使用 runas 命令：
runas /user:Administrator npm start
性能优化
为了获得最佳性能，请确保您的 SurrealDB 实例和 MCP 服务器配置在硬件资源上得到充分支持，包括足够的内存和 CPU 资源。
📄 许可证
文档中未提及许可证相关信息。
结束语
感谢您选择 SurrealDB MCP 服务器。如果在使用过程中有任何问题或建议，请随时联系我们的技术支持团队。