surrealmcp

SurrealMCP is the official MCP server for SurrealDB. It exposes SurrealDB capabilities to AI assistants, IDEs, and automation tools through the Model Context Protocol (MCP). The server supports multiple transport modes (stdio, HTTP, and Unix sockets) and can enforce authentication, rate limiting, health checks, and OpenTelemetry tracing. You can deploy it with Docker (recommended for quick setup) and then connect your MCP clients to the server using the appropriate command and transport settings. Examples include starting the server via Docker and connecting clients like Cursor, Claude Desktop, Copilot, or n8n by configuring their MCP server entries to point at the SurrealMCP instance. The server also supports environment variable overrides to configure the SurrealDB endpoint, namespace, database, and credentials when needed.

To use the included tools, configure your MCP client with a server entry named SurrealMCP (or a name of your choice) and provide the command and arguments shown in the deployment example. For most users, using the Docker deployment command provided in the README is sufficient: start the container and pass start as the final argument. If you need to connect to a specific SurrealDB instance or cloud endpoint, you can supply environment variables such as SURREALDB_URL, SURREALDB_NS, SURREALDB_DB, SURREALDB_USER, and SURREALDB_PASS in your MCP client configuration to authorize and direct operations to the desired SurrealDB instance.

Supported capabilities include: stdio-based MCP communication, HTTP requests, Unix socket connections, bearer token authentication (for SurrealDB Cloud), configurable rate limiting, health checks, structured logging, OpenTelemetry tracing, and an endpoint lockdown feature to constrain connections to a specific SurrealDB endpoint.

Prerequisites:

• Docker installed and running on your machine (recommended for quick setup).
• Optional: access to a Rust toolchain if you want to build SurrealMCP from source.

Installation options:

Option A: Deploy with Docker (recommended)

1. Ensure Docker is running and you have internet access.
2. Run the SurrealMCP container: docker run --rm -i --pull always surrealdb/surrealmcp:latest start
3. The MCP server will start and listen for connections on the configured transport (stdio, HTTP, or Unix sockets as supported by the image).

Option B: Build from source (advanced)

1. Install Rust and Cargo from https://www.rust-lang.org/tools/install
2. Clone the repository: git clone https://github.com/surrealdb/surrealmcp.git cd surrealmcp
3. Build and install locally: cargo install --path .
4. Run the server (adjust path as needed): surrealmcp start

Option C: Deployment with Docker (explicit) for environment overrides

1. Run the container with environment overrides as needed: docker run --rm -i
   -e SURREALDB_URL=ws://localhost:8000/rpc
   -e SURREALDB_NS=myapp
   -e SURREALDB_DB=production
   -e SURREALDB_USER=admin
   -e SURREALDB_PASS=password123
   --pull always surrealdb/surrealmcp:latest start

Notes and tips:

• If you are behind a proxy or require specific network settings, adjust Docker network configuration or environment variables accordingly.
• For production, consider enabling OpenTelemetry tracing and structured logging in your MCP clients to diagnose issues across MCP server interactions.
• Use the endpoint lockdown feature to restrict SurrealMCP to a single SurrealDB endpoint for better security.
• When using Docker, you can pin to a specific version tag instead of latest to ensure reproducible deployments (e.g., surrealdb/surrealmcp:1.0.0).
• If you plan to integrate with AI coding tools (Cursor, Claude Desktop, Copilot, Zed, n8n), follow the configuration examples in the README to wire up the MCP server with the appropriate transport (docker-based command with start) and provide any necessary environment variables for SurrealDB authentication.