The official MCP server for SurrealDB.

SurrealMCP

SurrealMCP is the official Model Context Protocol (MCP) server for SurrealDB and SurrealDB Cloud that enables AI assistants, AI agents, Developer IDEs, AI chatbots, and data platforms to interact with SurrealDB databases and SurrealDB Cloud.

Features

Multiple transport modes: Support for stdio, HTTP, and Unix socket connections
Authentication: Bearer token authentication with SurrealDB Cloud
Rate limiting: Configurable request rate limiting
Health checks: Built-in health checking
Structured logging: Comprehensive logging and metrics
OpenTelemetry support: Support for stdio and OpenTelemetry tracing
SurrealDB endpoint lockdown: Enable connecting to a specific SurrealDB endpoint only

Installation

Building from source

cargo install --path .

Deploying with Docker

docker run --rm -i --pull always surrealdb/surrealmcp:latest start

AI coding tools integration

SurrealMCP can be integrated with various AI coding tools and assistants to enable AI-powered database operations. Below are installation and configuration instructions for popular AI coding platforms.

Which AI assistant are you using?

Using Cursor? → View the Cursor installation instructions
Using Cline? → View the Cline installation instructions
Using Claude Desktop? → View the Claude installation instructions
Using GitHub Copilot in VS Code? → View the Copilot installation instructions
Using Roo Code in VS Code? → View the Roo Code installation instructions
Using Windsurf? → View the Windsurf installation instructions
Using Zed? → View the Zed installation instructions
Using n8n? → View the n8n integration instructions

Key Terms

MCP Server: A server that implements the Model Context Protocol, allowing AI assistants to access external tools and resources.
MCP Client: The IDE, application (like VS Code with Cline or Claude Desktop) that connects to MCP servers.
SurrealDB: A scalable, distributed, document-graph database with real-time capabilities.

Cursor installation

Installation for Cursor

Install SurrealMCP:

Build and install from source
Configure with Docker

Configure Cursor:
- Open Cursor
- Go to Settings > Cursor Settings
- Find the MCP Servers option and enable it
- Click on "New MCP Server"

Add the SurrealMCP configuration:

{
  "name": "SurrealDB",
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "--pull", "always",
    "surrealdb/surrealmcp:latest",
    "start"
  ]
}

Configuration with environment variables

{
  "name": "SurrealDB",
  "command": "surrealmcp",
  "args": ["start"],
  "env": {
    "SURREALDB_URL": "ws://localhost:8000/rpc",
    "SURREALDB_NS": "myapp",
    "SURREALDB_DB": "production",
    "SURREALDB_USER": "admin",
    "SURREALDB_PASS": "password123"
  }
}

Verify installation:
- Open Cursor Chat
- You should see SurrealDB tools available in the tools list

Cline installation

One-Click Installation for Cline VS Code Extension

Install SurrealMCP:

Build and install from source
Configure with Docker

Configure Cline:

Edit the file at: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Add the following configuration:

{
  "mcpServers": {
    "SurrealDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Configuration with environment variables

{
  "mcpServers": {
    "SurrealDB": {
      "command": "surrealmcp",
      "args": ["start"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000/rpc",
        "SURREALDB_NS": "myapp",
        "SURREALDB_DB": "production",
        "SURREALDB_USER": "admin",
        "SURREALDB_PASS": "password123"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Verify installation:
- Open Cline in VS Code
- Ask Cline to "list available MCP servers"
- You should see "SurrealDB" in the list

Claude installation

Installation for Claude Desktop App

Install SurrealMCP:

Build and install from source
Configure with Docker

Configure Claude Desktop:

Edit the Claude Desktop App's MCP settings file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "SurrealDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Configuration with environment variables

{
  "mcpServers": {
    "SurrealDB": {
      "command": "surrealmcp",
      "args": ["start"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000/rpc",
        "SURREALDB_NS": "myapp",
        "SURREALDB_DB": "production",
        "SURREALDB_USER": "admin",
        "SURREALDB_PASS": "password123"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Verify installation:
- Ask Claude to "list available MCP servers"
- You should see "SurrealDB" in the list

Copilot installation

Installation for GitHub Copilot in VS Code

Install SurrealMCP:

Build and install from source
Configure with Docker

Configure VSCode:

Create a file at: .vscode/mcp.json in your workspace

Add the following configuration:

{
  "servers": {
    "SurrealDB": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ]
    }
  }
}

Configuration with environment variables

{
  "inputs": [
    {
      "type": "promptString",
      "id": "surrealdb-url",
      "description": "SurrealDB URL",
      "default": "ws://localhost:8000/rpc"
    },
    {
      "type": "promptString",
      "id": "surrealdb-ns",
      "description": "SurrealDB Namespace"
    },
    {
      "type": "promptString",
      "id": "surrealdb-db",
      "description": "SurrealDB Database"
    },
    {
      "type": "promptString",
      "id": "surrealdb-user",
      "description": "SurrealDB Username"
    },
    {
      "type": "promptString",
      "id": "surrealdb-pass",
      "description": "SurrealDB Password",
      "password": true
    }
  ],
  "servers": {
    "SurrealDB": {
      "type": "stdio",
      "command": "surrealmcp",
      "args": ["start"],
      "env": {
        "SURREALDB_URL": "${input:surrealdb-url}",
        "SURREALDB_NS": "${input:surrealdb-ns}",
        "SURREALDB_DB": "${input:surrealdb-db}",
        "SURREALDB_USER": "${input:surrealdb-user}",
        "SURREALDB_PASS": "${input:surrealdb-pass}"
      }
    }
  }
}

Verify installation:
- Open GitHub Copilot Chat in VS Code
- Select "Agent" mode from the dropdown
- Click the "Tools" button to see available tools
- You should see "SurrealDB" tools in the list

Roo Code Installation

Installation for Roo Code in VS Code

Install SurrealMCP:

Build and install from source
Configure with Docker

Configure Roo Code:

Click the MCP icon in the top navigation of the Roo Code pane, then select "Edit MCP Settings" to open the configuration file.

Add the following configuration:

{
  "mcpServers": {
    "SurrealDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Configuration with environment variables

{
  "mcpServers": {
    "SurrealDB": {
      "command": "surrealmcp",
      "args": ["start"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000/rpc",
        "SURREALDB_NS": "myapp",
        "SURREALDB_DB": "production",
        "SURREALDB_USER": "admin",
        "SURREALDB_PASS": "password123"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Verify installation:
- Open Roo Code in VS Code
- Click the MCP icon to see available servers
- You should see "SurrealDB" in the list

Windsurf installation

Installation for Windsurf

Install SurrealMCP:

Build and install from source
Configure with Docker

Configure Windsurf:
- Open Windsurf on your system
- Navigate to the Settings page
- Go to the Cascade tab
- Find the Model Context Protocol (MCP) Servers section
- Click on "View raw config" to open the configuration file (typically at ~/.codeium/windsurf/mcp_config.json)

Add the SurrealMCP configuration:

{
  "servers": [
    {
      "name": "SurrealDB",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ]
    }
  ]
}

Configuration with environment variables

{
  "servers": [
    {
      "name": "SurrealDB",
      "command": "surrealmcp",
      "args": ["start"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000/rpc",
        "SURREALDB_NS": "myapp",
        "SURREALDB_DB": "production",
        "SURREALDB_USER": "admin",
        "SURREALDB_PASS": "password123"
      }
    }
  ]
}

Verify installation:
- Open Cascade in Windsurf
- You should see SurrealDB tools available in the tools list

Zed installation

Installation for Zed

Install SurrealMCP:

Build and install from source
Configure with Docker

Configure Zed:
- Open Zed
- Command Palette > Zed Settings

Add the SurrealMCP configuration: Under the context_servers key, add a new entry:

"surreal": {
   "source": "custom",
   "command": "docker",
   "args": [
     "run",
     "--rm",
     "-i",
     "--pull", "always",
     "surrealdb/surrealmcp:latest",
     "start"
   ],
   "enabled": true,
 }

Configuration with environment variables

"surreal": {
   "source": "custom",
   "command": "surrealmcp",
   "args": ["start"],
   "enabled": true,
   "env": {
     "SURREALDB_URL": "ws://localhost:8000/rpc",
     "SURREALDB_NS": "myapp",
     "SURREALDB_DB": "production",
     "SURREALDB_USER": "admin",
     "SURREALDB_PASS": "password123"
   }
 }

Verify installation:
- Open the Zed assistant panel
- You should see SurrealDB tools available in the tools list

Integration with n8n

You can integrate SurrealMCP with n8n using the MCP Client Tool node.

Deployment with Docker

Using Docker with STDIO

To use SurrealMCP without installing cargo you can use Docker. SurrealMCP runs locally via stdio with a single Docker command. Instantly start an in-memory or local database at the edge directly from your AI tool, with ephemeral or persisted data.

{
  "mcpServers": {
    "SurrealDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ]
    }
  }
}

Using Docker with HTTP

To use SurrealMCP without installing cargo you can use Docker. SurrealMCP can be run as an HTTP server with a single Docker command. Instantly start an in-memory or local database at the edge directly from your AI tool, with ephemeral or persisted data.

{
  "mcpServers": {
    "SurrealDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-p", "8080:8080",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start",
        "--bind-address", "127.0.0.1:8080",
        "--server-url", "http://localhost:8080"
      ]
    }
  }
}

Usage

Basic Usage

# Start as a STDIO server (default)
surrealmcp start

# Start as a HTTP server
surrealmcp start --bind-address 127.0.0.1:8000

# Start as a Unix socket
surrealmcp start --socket-path /tmp/surrealmcp.sock

Configuration Options

# Database connection
surrealmcp start \
  --endpoint ws://localhost:8000/rpc \
  --ns mynamespace \
  --db mydatabase \
  --user root \
  --pass root

# Server configuration
surrealmcp start \
  --bind-address 127.0.0.1:8000 \
  --server-url https://mcp.surrealdb.com \
  --cloud-auth-server https://auth.surrealdb.com \
  --expected-audience https://custom.audience.com/ \
  --rate-limit-rps 100 \
  --rate-limit-burst 200

# Disable authentication (for development)
surrealmcp start --bind-address 127.0.0.1:8000 --auth-disabled

Environment Variables

All configuration options can be set via environment variables:

export SURREALDB_URL="ws://localhost:8000/rpc"
export SURREALDB_NS="mynamespace"
export SURREALDB_DB="mydatabase"
export SURREALDB_USER="root"
export SURREALDB_PASS="root"
export SURREAL_MCP_BIND_ADDRESS="127.0.0.1:8000"
export SURREAL_MCP_SERVER_URL="https://mcp.surrealdb.com"
export SURREAL_CLOUD_AUTH_SERVER="https://auth.surrealdb.com"
export SURREAL_MCP_EXPECTED_AUDIENCE="https://custom.audience.com/"
export SURREAL_MCP_RATE_LIMIT_RPS="100"
export SURREAL_MCP_RATE_LIMIT_BURST="200"
export SURREAL_MCP_AUTH_REQUIRED="false"
export SURREAL_MCP_CLOUD_ACCESS_TOKEN="your_access_token_here"
export SURREAL_MCP_CLOUD_REFRESH_TOKEN="your_refresh_token_here"

surrealmcp start

Authentication

The server supports Bearer token authentication with SurrealDB Cloud. When authentication is enabled:

JWT Tokens: Validates JWT tokens using JWKS (JSON Web Key Set) from the auth server
JWE Tokens: Validates JWE header structure and issuer
Audience validation: Validates the aud claim against the expected audience
Issuer validation: Validates the iss claim against the expected issuer

Custom Audience Configuration

You can specify a custom expected audience for JWT token validation:

# Set a custom audience
surrealmcp start --expected-audience "https://myapp.com/api"

# Or via environment variable
export SURREAL_MCP_EXPECTED_AUDIENCE="https://myapp.com/api"
surrealmcp start

This is useful when:

Your application uses a custom audience in JWT tokens
You want to restrict tokens to specific applications
You're integrating with custom authentication systems

Pre-configured Cloud Authentication Tokens

For SurrealDB Cloud operations, you can provide pre-configured access and refresh tokens instead of fetching them dynamically:

# Set pre-configured tokens
surrealmcp start \
  --access-token "your_access_token_here" \
  --refresh-token "your_refresh_token_here"

# Or via environment variables
export SURREAL_MCP_CLOUD_ACCESS_TOKEN="your_access_token_here"
export SURREAL_MCP_CLOUD_REFRESH_TOKEN="your_refresh_token_here"
surrealmcp start

This is useful when:

You have existing tokens from a previous authentication flow
You want to avoid the token fetching process
You're running in environments where token fetching is not possible
You want to use long-lived tokens for automated operations

Note: When both access and refresh tokens are provided, the server will use these tokens for all SurrealDB Cloud API operations instead of attempting to fetch new tokens.

Client Integration

When integrating with the MCP server, clients should:

Discover the authorization configuration:

curl http://localhost:8000/.well-known/oauth-protected-resource

Request a token from the authorization server using the returned audience:

# Example Auth0 token request
curl -X POST https://auth.surrealdb.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "audience": "https://custom.audience.com/",
    "grant_type": "client_credentials"
  }'

Use the token for authenticated requests:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/mcp

The audience value ensures that tokens are issued specifically for the MCP server instance.

Available Tools

SurrealMCP provides a comprehensive set of tools for interacting with SurrealDB databases and SurrealDB Cloud:

Database Operations

Query: Execute raw SurrealQL queries with parameterized inputs
Select: Query records with filtering, sorting, and pagination
Insert: Insert new records into tables
Create: Create single records with specific IDs
Upsert: Create or update records based on conditions
Update: Modify existing records with patch operations
Delete: Remove records from the database
Relate: Create relationships between records

Connection Management

Connect Endpoint: Connect to different SurrealDB endpoints including:
- Local instances: memory, file:/path, rocksdb:/path
- Remote instances: ws://host:port, http://host:port
- SurrealDB Cloud instances: cloud:instance_id
Use Namespace: Switch between namespaces
Use Database: Switch between databases
List Namespaces: List the defined namespaces
List Databases: List the defined databases
Disconnect Endpoint: Close the current connection

SurrealDB Cloud Operations

List Cloud Organizations: Get available organizations
List Cloud Instances: Get instances for an organization
Create Cloud Instance: Create new cloud instances
Pause/Resume Cloud Instance: Manage instance lifecycle
Get Cloud Instance Status: Check instance health and backups

Cloud Connection Feature

The new cloud connection feature allows you to connect directly to SurrealDB Cloud instances using the connect_endpoint tool with the cloud:instance_id format:

# Connect to a SurrealDB Cloud instance
connect_endpoint('cloud:abc123def456', 'myapp', 'production')

This feature:

Automatically fetches authentication tokens from the SurrealDB Cloud API
Validates instance readiness before connecting
Establishes secure connections using the temporary auth token
Supports namespace and database specification
Handles connection errors gracefully with detailed logging

API Endpoints

Health Check

curl http://localhost:8000/health

Authentication Discovery

curl http://localhost:8000/.well-known/oauth-protected-resource

This endpoint returns the authorization server configuration including the expected audience:

{
  "resource": "https://mcp.surrealdb.com",
  "authorization_servers": ["https://auth.surrealdb.com"],
  "bearer_methods_supported": ["header"],
  "audience": "https://mcp.surrealdb.com/"
}

Clients should use the audience value when requesting tokens from the authorization server.

MCP Protocol

The server implements the Model Context Protocol and can be used with MCP-compatible clients.

Development

Building

cargo build

Testing

cargo test

Running with Docker

docker build -t surrealmcp .
docker run -p 8000:8000 surrealmcp start --bind-address 0.0.0.0:8000

License

This project is licensed under the Business Source License.

SurrealDB

The official MCP server for SurrealDB.

SurrealMCP

Features

Installation

Building from source

Deploying with Docker

AI coding tools integration

Which AI assistant are you using?

Key Terms

Cursor installation

Installation for Cursor

Cline installation

One-Click Installation for Cline VS Code Extension

Claude installation

Installation for Claude Desktop App

Copilot installation

Installation for GitHub Copilot in VS Code

Roo Code Installation

Installation for Roo Code in VS Code

Windsurf installation

Installation for Windsurf

Zed installation

Installation for Zed

Integration with n8n

Deployment with Docker

Using Docker with STDIO

Using Docker with HTTP

Usage

Basic Usage

Configuration Options

Environment Variables

Authentication

Custom Audience Configuration

Pre-configured Cloud Authentication Tokens

Client Integration

Available Tools

Database Operations

Connection Management

SurrealDB Cloud Operations

Cloud Connection Feature

API Endpoints

Health Check

Authentication Discovery

MCP Protocol

Development

Building

Testing

Running with Docker

License

Be the First to Experience MCP Now