MCP Container

surrealmcp

The official MCP server for SurrealDB

GitHubWebsiteDocs

GitHubスター

36

ユーザー評価

未評価

お気に入り

0

閲覧数

8

フォーク

2

イシュー

3

README

 

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?
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
  1. Install SurrealMCP:

  1. Configure Cursor:

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

  2. 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"
  }
}

  3. 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
  1. Install SurrealMCP:

  1. 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": []
    }
  }
}

  2. 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
  1. Install SurrealMCP:

  1. 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": []
    }
  }
}

  2. 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
  1. Install SurrealMCP:

  1. 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}"
      }
    }
  }
}

  2. 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
  1. Install SurrealMCP:

  1. 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": []
    }
  }
}

  2. 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
  1. Install SurrealMCP:

  1. 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)

  2. 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"
      }
    }
  ]
}

  3. Verify installation:

    • Open Cascade in Windsurf
    • You should see SurrealDB tools available in the tools list
Zed installation
Installation for Zed
  1. Install SurrealMCP:

  1. Configure Zed:

    • Open Zed
    • Command Palette > Zed Settings

  2. 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"
   }
 }

  3. 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:

  1. JWT Tokens: Validates JWT tokens using JWKS (JSON Web Key Set) from the auth server
  2. JWE Tokens: Validates JWE header structure and issuer
  3. Audience validation: Validates the aud claim against the expected audience
  4. 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:

  1. Discover the authorization configuration:

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

  2. 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"
  }'

  3. 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
SurrealDB

A scalable, distributed, collaborative, document-graph database, for the realtime web

United Kingdom
GitHub

1,297

フォロワー

89

リポジトリ

0

Gist

0

貢献数

タグ
databasemcpmcp-servermodel-context-protocolsurrealsurrealdb
関連するMCP
mcp-baserow logo
mcp-baserow
1

MCP server for Baserow API integration - Enable AI assistants to interact with Baserow databases

TypeScript
dbhub logo
dbhub
1252

DBHubは、Model Context Protocol (MCP)サーバーインターフェースを実装したユニバーサルデータベースゲートウェイです。このゲートウェイにより、MCP対応クライアントは異なるデータベースに接続し、探索することができます。開発者向けのDevSecOpsプラットフォームとして、データベース管理の効率を向上させます。

TypeScript
mcp-neo4j logo
mcp-neo4j
673

Model Context Protocol with Neo4j

Python