home / mcp / surrealdb mcp server
Provides an MCP interface to interact with SurrealDB, enabling AI assistants to run SurrealQL queries, manage CRUD operations, and traverse graph relationships.
Configuration
View docs{
"mcpServers": {
"lfnovo-surreal-mcp": {
"command": "uvx",
"args": [
"surreal-mcp"
],
"env": {
"SURREAL_URL": "ws://localhost:8000/rpc",
"SURREAL_USER": "root",
"SURREAL_DATABASE": "test",
"SURREAL_PASSWORD": "root",
"SURREAL_NAMESPACE": "test"
}
}
}
}You enable AI assistants to securely and directly interact with SurrealDB using an MCP server. This bridge provides a consistent, intent-friendly interface for running SurrealQL queries, performing CRUD operations, managing graph relationships, and handling bulk actions, all while leveraging SurrealDB features like record IDs and graph edges. You can connect from MCP clients to execute powerful database operations without writing boilerplate code.
Connect your MCP client to the SurrealDB MCP Server to perform operations. You can execute raw SurrealQL queries, create and read records, update and delete records, and manage relationships between entities. When you call tools like query, create, or relate, your client can override the namespace and database for specific operations, enabling multi-database workflows within a single session.
Prerequisites you need to meet before running the server:
Python 3.10 or higher
SurrealDB instance (local or remote)
MCP-compatible client (Claude Desktop, MCP CLI, etc.)The server uses environment variables to configure the SurrealDB connection and default namespace/database settings. You can either set them in a .env file or export them in your shell session. If you do not provide namespace and database overrides in each tool call, the environment defaults will be used.
SURREAL_URL=ws://localhost:8000/rpc
SURREAL_USER=root
SURREAL_PASSWORD=root
SURREAL_NAMESPACE=test
SURREAL_DATABASE=testTo run the SurrealDB MCP Server via a local MCP client, you can use either a direct runtime command or a managed runtime tool like uvx. The following examples show how to set the necessary environment variables and start the server.
# Option 1: Run directly from PyPI
uvx surreal-mcp
# Option 2: Run from GitHub (example path)
uvx --from git+https://github.com/yourusername/surreal-mcp.git surreal-mcp- Use strong, unique credentials for SurrealDB and limit network exposure to trusted clients. - Prefer short-lived tokens or secrets and rotate them regularly. - Enable proper access controls and least-privilege permissions for MCP operations.
You can perform typical data tasks across namespaces and databases by overriding defaults at call time. For example, switch namespace/database for a specific operation or bulk upload data to a different database, then query across relationships to analyze connected data.
If you encounter connection errors, verify that SurrealDB is reachable at the URL in SURREAL_URL and that the user credentials match. Check that the target namespace and database exist, and ensure the MCP server has permission to access them.
The server emphasizes multi-database support, type-safe handling of SurrealDB RecordIDs, and efficient connection pooling to maximize throughput when handling bulk operations.
Execute raw SurrealQL queries for complex operations.
Retrieve all records from a table or a specific record by ID.
Create a new record with auto-generated ID.
Replace entire record content while preserving ID and timestamps.
Permanently remove a record from the database.
Partially update specific fields without affecting others.
Apply JSON Patch operations to records.
Create or update a record with a specific ID.
Bulk insert multiple records efficiently.
Create graph relationships between records.