🚀 SurrealDB MCP 服务器
这是一个模型上下文协议（MCP）服务器，它能让 AI 助手与 SurrealDB 数据库进行交互。借助该服务器，AI 助手可以通过标准化接口执行各类数据库操作，为数据处理带来便利。
🚀 快速开始
SurrealDB MCP 服务器通过模型上下文协议，为 AI 助手和 SurrealDB 之间搭建了桥梁，提供了标准化的数据库操作接口。这使得大语言模型（LLMs）能够：
- 执行复杂的 SurrealQL 查询
- 对记录进行 CRUD 操作
- 管理图关系
- 高效处理批量操作
- 利用 SurrealDB 的独特功能，如记录 ID 和图边
✨ 主要特性
- 全面支持 SurrealQL：可直接执行任何 SurrealQL 查询。
- 全面的 CRUD 操作：轻松创建、读取、更新和删除记录。
- 图数据库操作：创建和遍历记录之间的关系。
- 批量操作：高效插入多条记录。
- 智能更新：支持全量更新、合并和补丁操作。
- 类型安全：正确处理 SurrealDB 的 RecordIDs。
- 连接池：高效管理数据库连接。
- 详细文档：提供丰富的文档字符串，便于 AI 理解。
📦 安装指南
使用 uvx（最简单 - 无需安装）
# 直接从 PyPI 运行（发布后）
uvx surreal-mcp
# 或者从 GitHub 运行
uvx --from git+https://github.com/yourusername/surreal-mcp.git surreal-mcp
使用 uv（开发推荐）
# 克隆仓库
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp
# 安装依赖
uv sync
# 运行服务器（多种方式）
uv run surreal-mcp
# 或者
uv run python -m surreal_mcp
# 或者
uv run python main.py
使用 pip
# 克隆仓库
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # 在 Windows 上：venv\Scripts\activate
# 安装包
pip install -e .
# 运行服务器
surreal-mcp
# 或者
python -m surreal_mcp
📚 详细文档
配置
服务器需要以下环境变量：
| 属性 | 详情 |
|---|---|
SURREAL_URL |
SurrealDB 连接 URL，例如 ws://localhost:8000/rpc |
SURREAL_USER |
数据库用户名，例如 root |
SURREAL_PASSWORD |
数据库密码，例如 root |
SURREAL_NAMESPACE |
SurrealDB 命名空间，例如 test |
SURREAL_DATABASE |
SurrealDB 数据库，例如 test |
设置环境变量
你可以将 .env.example 复制到 .env 并更新为你的值：
cp .env.example .env
# 使用你的数据库凭证编辑 .env
或者手动设置：
export SURREAL_URL="ws://localhost:8000/rpc"
export SURREAL_USER="root"
export SURREAL_PASSWORD="root"
export SURREAL_NAMESPACE="test"
export SURREAL_DATABASE="test"
MCP 客户端配置
添加到你的 MCP 客户端设置（例如，Claude Desktop）： 使用 uvx（推荐）：
{
"mcpServers": {
"surrealdb": {
"command": "uvx",
"args": ["surreal-mcp"],
"env": {
"SURREAL_URL": "ws://localhost:8000/rpc",
"SURREAL_USER": "root",
"SURREAL_PASSWORD": "root",
"SURREAL_NAMESPACE": "test",
"SURREAL_DATABASE": "test"
}
}
}
}
使用本地安装：
{
"mcpServers": {
"surrealdb": {
"command": "uv",
"args": ["run", "surreal-mcp"],
"env": {
"SURREAL_URL": "ws://localhost:8000/rpc",
"SURREAL_USER": "root",
"SURREAL_PASSWORD": "root",
"SURREAL_NAMESPACE": "test",
"SURREAL_DATABASE": "test"
}
}
}
}
可用工具
1. query
执行原始 SurrealQL 查询以进行复杂操作。
-- 示例：带有图遍历的复杂查询
SELECT *, ->purchased->product FROM user WHERE age > 25
2. select
从表中检索所有记录或按 ID 检索特定记录。
# 获取所有用户
select("user")
# 获取特定用户
select("user", "john")
3. create
创建具有自动生成 ID 的新记录。
create("user", {
"name": "Alice",
"email": "alice@example.com",
"age": 30
})
4. update
替换整个记录内容（保留 ID 和时间戳）。
update("user:john", {
"name": "John Smith",
"email": "john.smith@example.com",
"age": 31
})
5. delete
从数据库中永久删除记录。
delete("user:john")
6. merge
部分更新特定字段，而不影响其他字段。
merge("user:john", {
"email": "newemail@example.com",
"verified": True
})
7. patch
对记录应用 JSON Patch 操作（RFC 6902）。
patch("user:john", [
{"op": "replace", "path": "/email", "value": "new@example.com"},
{"op": "add", "path": "/verified", "value": True}
])
8. upsert
使用特定 ID 创建或更新记录。
upsert("settings:global", {
"theme": "dark",
"language": "en"
})
9. insert
高效批量插入多条记录。
insert("product", [
{"name": "Laptop", "price": 999.99},
{"name": "Mouse", "price": 29.99},
{"name": "Keyboard", "price": 79.99}
])
10. relate
在记录之间创建图关系。
relate(
"user:john", # from
"purchased", # 关系名称
"product:laptop-123", # to
{"quantity": 1, "date": "2024-01-15"} # 关系数据
)
💻 使用示例
基本 CRUD 操作
# 创建用户
user = create("user", {"name": "Alice", "email": "alice@example.com"})
# 更新特定字段
merge(user["id"], {"verified": True, "last_login": "2024-01-01"})
# 带条件查询
results = query("SELECT * FROM user WHERE verified = true ORDER BY created DESC")
# 完成后删除
delete(user["id"])
处理关系
# 创建实体
user = create("user", {"name": "John"})
product = create("product", {"name": "Laptop", "price": 999})
# 创建关系
relate(user["id"], "purchased", product["id"], {
"quantity": 1,
"total": 999,
"date": "2024-01-15"
})
# 查询关系
purchases = query(f"SELECT * FROM {user['id']}->purchased->product")
批量操作
# 插入多条记录
products = insert("product", [
{"name": "Laptop", "category": "Electronics", "price": 999},
{"name": "Mouse", "category": "Electronics", "price": 29},
{"name": "Desk", "category": "Furniture", "price": 299}
])
# 批量更新查询
query("UPDATE product SET on_sale = true WHERE category = 'Electronics'")
🔧 技术细节
服务器采用以下技术构建：
- FastMCP：简化的 MCP 服务器实现
- SurrealDB Python SDK：官方数据库客户端
- 连接池：高效管理连接
- 异步/等待：非阻塞数据库操作
测试
项目包含使用 pytest 的全面测试套件。
前提条件
- 本地运行的 SurrealDB 实例
- 测试数据库访问权限（使用临时测试数据库）
运行测试
# 确保 SurrealDB 正在运行
surreal start --user root --pass root
# 运行所有测试
uv run pytest
# 运行并查看覆盖率
uv run pytest --cov=surreal_mcp
# 运行特定测试文件
uv run pytest tests/test_tools.py
# 运行特定测试类或方法
uv run pytest tests/test_tools.py::TestQueryTool
uv run pytest tests/test_tools.py::TestQueryTool::test_query_simple
# 运行并输出详细信息
uv run pytest -v
# 仅运行匹配模式的测试
uv run pytest -k "test_create"
测试结构
tests/
├── __init__.py
├── conftest.py # 测试夹具和配置
├── test_tools.py # 所有 MCP 工具的测试
└── test_server.py # 服务器配置的测试
编写测试
测试套件包含常见测试数据的夹具：
clean_db- 确保数据库状态干净sample_user_data- 示例用户数据created_user- 预创建的用户记录created_product- 预创建的产品记录
示例测试：
@pytest.mark.asyncio
async def test_create_user(clean_db, sample_user_data):
result = await mcp._tools["create"].func(
table="user",
data=sample_user_data
)
assert result["success"] is True
assert result["data"]["email"] == sample_user_data["email"]
贡献
欢迎贡献代码！请随时提交拉取请求。
- 分叉仓库
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 打开拉取请求
📄 许可证
本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。
致谢
- SurrealDB 提供了出色的图数据库
- FastMCP 简化了 MCP 服务器开发
- Model Context Protocol 提供了标准化的 AI 工具接口
支持
为 SurrealDB 和 MCP 社区精心打造 ❤️