Enables AI assistants to interact with SurrealDB databases, supporting SurrealQL queries, CRUD operations, graph relationship management, and bulk operations while handling SurrealDB's unique features like record IDs and graph edges.
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
- 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)
Using uv (Recommended for Development)
Using pip
� Configuration
The server requires the following environment variables:
Variable | Description | Example |
---|---|---|
SURREAL_URL | SurrealDB connection URL | ws://localhost:8000/rpc |
SURREAL_USER | Database username | root |
SURREAL_PASSWORD | Database password | root |
SURREAL_NAMESPACE | SurrealDB namespace | test |
SURREAL_DATABASE | SurrealDB database | test |
Setting Environment Variables
You can copy .env.example
to .env
and update with your values:
Or set them manually:
MCP Client Configuration
Add to your MCP client settings (e.g., Claude Desktop):
Using uvx (recommended):
Using local installation:
=' Available Tools
1. query
Execute raw SurrealQL queries for complex operations.
2. select
Retrieve all records from a table or a specific record by ID.
3. create
Create a new record with auto-generated ID.
4. update
Replace entire record content (preserves ID and timestamps).
5. delete
Permanently remove a record from the database.
6. merge
Partially update specific fields without affecting others.
7. patch
Apply JSON Patch operations (RFC 6902) to records.
8. upsert
Create or update a record with specific ID.
9. insert
Bulk insert multiple records efficiently.
10. relate
Create graph relationships between records.
=� Examples
Basic CRUD Operations
Working with Relationships
Bulk Operations
<� Architecture
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
Test Structure
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:
> 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
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
MCP Server for SurrealDB - Bridge AI assistants with SurrealDB databases
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server that provides tools for interacting with Supabase databases, storage, and edge functions.Last updated -1442JavaScriptMIT License
- -securityAlicense-qualityMCP Server for interacting with Cube semantic layers that provides tools for querying and describing data from Cube deployments.Last updated -8PythonGPL 3.0
- -securityAlicense-qualityThe Multi DB MCP Server is a high-performance implementation of the Database Model Context Protocol designed to revolutionize how AI agents interact with databases. Currently supporting MySQL and PostgreSQL databases.Last updated -254GoMIT License
- -securityAlicense-qualityAn MCP server that enables AI applications to interact with DiceDB databases.Last updated -5GoMIT License