SurrealDB MCP Server

=� 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