SurrealDB MCP Server
A Model Context Protocol (MCP) server that enables AI assistants to interact with SurrealDB databases
=� Overview
The SurrealDB MCP Server bridges the gap between AI assistants and SurrealDB, providing a standardized interface for database operations through the Model Context Protocol. This enables LLMs to:
- Execute complex SurrealQL queries
- Perform CRUD operations on records
- Manage graph relationships
- Handle bulk operations efficiently
- Work with SurrealDB's unique features like record IDs and graph edges
Features
- Full SurrealQL Support: Execute any SurrealQL query directly
- Comprehensive CRUD Operations: Create, read, update, delete with ease
- Graph Database Operations: Create and traverse relationships between records
- Bulk Operations: Efficient multi-record inserts
- Smart Updates: Full updates, merges, and patches
- Type-Safe: Proper handling of SurrealDB's RecordIDs
- Connection Pooling: Efficient database connection management
- Multi-Database Support: Override namespace/database per tool call
- Detailed Documentation: Extensive docstrings for AI comprehension
=� Prerequisites
- Python 3.10 or higher
- SurrealDB instance (local or remote)
- MCP-compatible client (Claude Desktop, MCP CLI, etc.)
=� Installation
Using uvx (Simplest - No Installation Required)
# 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
Using uv (Recommended for Development)
# 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
Using 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
� Configuration
The server uses environment variables for configuration.
Required Variables (at startup)
| Variable | Description | Example |
|---|---|---|
SURREAL_URL |
SurrealDB connection URL | ws://localhost:8000/rpc |
SURREAL_USER |
Database username | root |
SURREAL_PASSWORD |
Database password | root |
Optional Variables (can be overridden per tool call)
| Variable | Description | Example |
|---|---|---|
SURREAL_NAMESPACE |
Default SurrealDB namespace | test |
SURREAL_DATABASE |
Default SurrealDB database | test |
Note: If
SURREAL_NAMESPACEandSURREAL_DATABASEare not set as environment variables, you must providenamespaceanddatabaseparameters in each tool call.
Setting Environment Variables
You can copy .env.example to .env and update with your values:
cp .env.example .env
# Edit .env with your database credentials
Or set them manually:
export SURREAL_URL="ws://localhost:8000/rpc"
export SURREAL_USER="root"
export SURREAL_PASSWORD="root"
export SURREAL_NAMESPACE="test"
export SURREAL_DATABASE="test"
MCP Client Configuration
Add to your MCP client settings (e.g., Claude Desktop):
Using uvx (recommended):
{
"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"
}
}
}
}
Using local installation:
{
"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"
}
}
}
}
=' Available Tools
All tools support optional namespace and database parameters to override the default values from environment variables.
1. query
Execute raw SurrealQL queries for complex operations.
-- 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
Retrieve all records from a table or a specific record by 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
Create a new record with auto-generated ID.
create("user", {
"name": "Alice",
"email": "alice@example.com",
"age": 30
})
4. update
Replace entire record content (preserves ID and timestamps).
update("user:john", {
"name": "John Smith",
"email": "john.smith@example.com",
"age": 31
})
5. delete
Permanently remove a record from the database.
delete("user:john")
6. merge
Partially update specific fields without affecting others.
merge("user:john", {
"email": "newemail@example.com",
"verified": True
})
7. patch
Apply JSON Patch operations (RFC 6902) to records.
patch("user:john", [
{"op": "replace", "path": "/email", "value": "new@example.com"},
{"op": "add", "path": "/verified", "value": True}
])
8. upsert
Create or update a record with specific ID.
upsert("settings:global", {
"theme": "dark",
"language": "en"
})
9. insert
Bulk insert multiple records efficiently.
insert("product", [
{"name": "Laptop", "price": 999.99},
{"name": "Mouse", "price": 29.99},
{"name": "Keyboard", "price": 79.99}
])
10. relate
Create graph relationships between records.
relate(
"user:john", # from
"purchased", # relation name
"product:laptop-123", # to
{"quantity": 1, "date": "2024-01-15"} # relation data
)
=� Examples
Basic CRUD Operations
# Create a user
user = create("user", {"name": "Alice", "email": "alice@example.com"})
# 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"])
Working with Relationships
# 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")
Bulk Operations
# 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
<� Architecture
=======
Multi-Database Operations
You can work with multiple databases in a single session by using the namespace and database parameters:
# 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")
Behavior Summary:
| Scenario | Result |
|---|---|
| Env vars set, no params | Uses pooled connection (best performance) |
| Env vars set, params provided | Uses override connection with specified namespace/database |
| No env vars, params provided | Uses override connection with specified namespace/database |
| No env vars, no params | Fails with clear error message |
<� Architecture
main
The server is built with:
- FastMCP: Simplified MCP server implementation
- SurrealDB Python SDK: Official database client
- Connection Pooling: Efficient connection management
- Async/Await: Non-blocking database operations
>� Testing
The project includes a comprehensive test suite using pytest.
Prerequisites
- SurrealDB instance running locally
- Test database access (uses temporary test databases)
Running Tests
# 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"
Test Structure
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
Writing Tests
The test suite includes fixtures for common test data:
clean_db- Ensures clean database statesample_user_data- Sample user datacreated_user- Pre-created user recordcreated_product- Pre-created product record
Example test:
@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"]
> Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
=� License
This project is licensed under the MIT License - see the LICENSE file for details.
=O Acknowledgments
- SurrealDB for the amazing graph database
- FastMCP for simplifying MCP server development
- Model Context Protocol for the standardized AI-tool interface
=� Support
- =� Email: your.email@example.com
- =� Discord: Join our server
- = Issues: GitHub Issues
Metadata
Release files for iflow-mcp_lfnovo-surreal-mcp 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_lfnovo_surreal_mcp-0.2.1.tar.gz | 248.8 kB | Without provenance | Details for iflow_mcp_lfnovo_surreal_mcp-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_lfnovo_surreal_mcp-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_lfnovo_surreal_mcp-0.2.1-py3-none-any.whl |
Total release size: 266.2 kB
Release files / iflow_mcp_lfnovo_surreal_mcp-0.2.1.tar.gz
| Download URL | iflow_mcp_lfnovo_surreal_mcp-0.2.1.tar.gz |
|---|---|
| Size | 248.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c04cd873c524219a88ba62a81820d5ce39cc2870870a06e1f7501e6c433e068
|
|
BLAKE2b-256 checksum How to use checksums |
290c22706c2d10e178cfb9b6c3b318201cab0361578a64fd2edce193eb270b20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_lfnovo_surreal_mcp-0.2.1-py3-none-any.whl
| Download URL | iflow_mcp_lfnovo_surreal_mcp-0.2.1-py3-none-any.whl |
|---|---|
| Size | 17.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d8b227899580e61fb6f5ff33cb6b7a702cd229e9b61cdd718c4285102b7073f6
|
|
BLAKE2b-256 checksum How to use checksums |
f107b0d0e416c695c7897185d4ceebbd29149c7a1c0c7a716929aef234f79baf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_lfnovo-surreal-mcp 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.