Surreal Mcp

SurrealDB MCP Server

=� 概览

SurrealDB MCP 服务在 AI 助手与 SurrealDB 之间搭建桥梁，通过模型上下文协议为数据库操作提供标准化接口。这使大模型能够：

• 执行复杂的 SurrealQL 查询
• 对记录执行 CRUD 操作
• 管理图关系
• 高效处理批量操作
• 使用 SurrealDB 的独特功能，例如记录 ID 和图边

功能特性

• 全面支持 SurrealQL：直接执行任何 SurrealQL 查询
• 完整的 CRUD 操作：轻松创建、读取、更新和删除数据
• 图数据库操作：创建和遍历记录之间的关系
• 批量操作：高效插入多条记录
• 智能更新：支持完整更新、合并和补丁
• 类型安全：正确处理 SurrealDB 的 RecordID
• 连接池：高效管理数据库连接
• 多数据库支持：每次工具调用均可覆盖命名空间／数据库
• 详细文档：提供丰富的文档字符串，便于 AI 理解

=� 前置条件

• Python 3.10 或更高版本
• SurrealDB 实例（本地或远程）
• 兼容 MCP 的客户端（Claude Desktop、MCP CLI 等）

=� 安装

使用 uvx（最简单——无需安装）

# Run directly from PyPI (once published)
uvx surreal-mcp

# Or run from GitHub
uvx --from git+https://github.com/yourusername/surreal-mcp.git surreal-mcp

使用 uv（推荐用于开发）

# Clone the repository
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp

# Install dependencies
uv sync

# Run the server (multiple ways)
uv run surreal-mcp
# or
uv run python -m surreal_mcp
# or
uv run python main.py

使用 pip

# Clone the repository
git clone https://github.com/yourusername/surreal-mcp.git
cd surreal-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install package
pip install -e .

# Run the server
surreal-mcp
# or
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

注意：如果未将 SURREAL_NAMESPACE 和 SURREAL_DATABASE 设置为环境变量，则必须在每次工具调用中提供 namespace 和 database 参数。

设置环境变量

你可以将 .env.example 复制为 .env，并更新其中的值：

cp .env.example .env
# Edit .env with your database credentials

也可以手动设置：

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"
      }
    }
  }
}

=' 可用工具

所有工具都支持可选的 namespace 和 database 参数，用于覆盖环境变量中的默认值。

1. query

执行原始 SurrealQL 查询以完成复杂操作。

-- Example: Complex query with graph traversal
SELECT *, ->purchased->product FROM user WHERE age > 25

# Query with namespace/database override
query("SELECT * FROM user", namespace="production", database="main")

2. select

获取表中的所有记录，或按 ID 获取特定记录。

# Get all users
select("user")

# Get specific user
select("user", "john")

# Select from a different database
select("user", namespace="other_ns", database="other_db")

3. create

创建一条具有自动生成 ID 的新记录。

create("user", {
    "name": "Alice",
    "email": "[email protected]",
    "age": 30
})

4. update

替换整条记录的内容（保留 ID 和时间戳）。

update("user:john", {
    "name": "John Smith",
    "email": "[email protected]",
    "age": 31
})

5. delete

从数据库中永久删除一条记录。

delete("user:john")

6. merge

仅更新指定字段，不影响其他字段。

merge("user:john", {
    "email": "[email protected]",
    "verified": True
})

7. patch

将 JSON Patch 操作（RFC 6902）应用于记录。

patch("user:john", [
    {"op": "replace", "path": "/email", "value": "[email protected]"},
    {"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",           # relation name
    "product:laptop-123",  # to
    {"quantity": 1, "date": "2024-01-15"}  # relation data
)

=� 示例

基本 CRUD 操作

# Create a user
user = create("user", {"name": "Alice", "email": "[email protected]"})

# Update specific fields
merge(user["id"], {"verified": True, "last_login": "2024-01-01"})

# Query with conditions
results = query("SELECT * FROM user WHERE verified = true ORDER BY created DESC")

# Delete when done
delete(user["id"])

使用关系

# Create entities
user = create("user", {"name": "John"})
product = create("product", {"name": "Laptop", "price": 999})

# Create relationship
relate(user["id"], "purchased", product["id"], {
    "quantity": 1,
    "total": 999,
    "date": "2024-01-15"
})

# Query relationships
purchases = query(f"SELECT * FROM {user['id']}->purchased->product")

批量操作

# Insert multiple records
products = insert("product", [
    {"name": "Laptop", "category": "Electronics", "price": 999},
    {"name": "Mouse", "category": "Electronics", "price": 29},
    {"name": "Desk", "category": "Furniture", "price": 299}
])

# Bulk update with query
query("UPDATE product SET on_sale = true WHERE category = 'Electronics'")

<<<<<<< HEAD

<� 架构

=======

多数据库操作

你可以在单个会话中使用 namespace 和 database 参数操作多个数据库：

# Create a record in the production database
create("user", {"name": "Alice"}, namespace="prod", database="main")

# Query from staging database
select("user", namespace="staging", database="main")

# Copy data between databases
users = select("user", namespace="staging", database="main")
for user in users["data"]:
    create("user", user, namespace="prod", database="main")

行为摘要：

场景	结果
已设置环境变量，未提供参数	使用连接池连接（性能最佳）
已设置环境变量，提供了参数	使用指定 namespace/database 的覆盖连接
未设置环境变量，提供了参数	使用指定 namespace/database 的覆盖连接
未设置环境变量，也未提供参数	失败并显示清晰的错误消息

<� 架构

main

此服务基于以下组件构建：

• FastMCP：简化 MCP 服务的实现
• SurrealDB Python SDK：官方数据库客户端
• 连接池：高效的连接管理
• Async/Await：非阻塞数据库操作

>� 测试

本项目使用 pytest 构建了全面的测试套件。

前置条件

• 本地运行的 SurrealDB 实例
• 测试数据库访问权限（使用临时测试数据库）

运行测试

# Make sure SurrealDB is running
surreal start --user root --pass root

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=surreal_mcp

# Run specific test file
uv run pytest tests/test_tools.py

# Run specific test class or method
uv run pytest tests/test_tools.py::TestQueryTool
uv run pytest tests/test_tools.py::TestQueryTool::test_query_simple

# Run with verbose output
uv run pytest -v

# Run only tests matching a pattern
uv run pytest -k "test_create"

测试结构

tests/
├── __init__.py
├── conftest.py              # Fixtures and test configuration
├── test_tools.py            # Tests for all MCP tools
├── test_server.py           # Tests for server configuration
└── test_namespace_override.py  # Tests for namespace/database override

编写测试

测试套件包含用于常见测试数据的 fixture：

• 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"]

> 贡献

欢迎贡献！欢迎提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 将更改推送到该分支（git push origin feature/AmazingFeature）
5. 发起 Pull Request

=� 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

=O 致谢

• 感谢 SurrealDB 提供出色的图数据库
• 感谢 FastMCP 简化 MCP 服务开发
• 感谢 Model Context Protocol 提供标准化的 AI 工具接口

=� 支持

• =� 电子邮件：[email protected]
• =� Discord：加入我们的服务器
• = Issues：GitHub Issues

---