SurrealDB MCP Server

A Model Context Protocol (MCP) server that provides a standardized interface for AI assistants to interact with a SurrealDB database. This server enables AI systems to query and manipulate data within a configured SurrealDB instance.

Note for AI Assistants: If you are an AI assistant (like Claude, Cline, Copilot, etc.) reading this documentation, please refer to the llms-install.md file for detailed instructions specifically designed for you to help users install and configure this MCP server.

Key Terms

• MCP Server: A server that implements the Model Context Protocol, allowing AI assistants to access external tools and resources
• MCP Host: The 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

Available Tools

The server exposes the following tools for interacting with SurrealDB:

• query: Execute a raw SurrealQL query.
• select: Select records from a table (all or by specific ID).
• create: Create a single new record in a table.
• update: Update a specific record, replacing its content.
• delete: Delete a specific record by ID.
• merge: Merge data into a specific record (partial update).
• patch: Apply JSON Patch operations to a specific record.
• upsert: Create a record if it doesn't exist, or update it if it does.
• insert: Insert multiple records into a table.
• insertRelation: Create a graph relation (edge) between two records.

(Refer to the MCP host's tool listing for detailed input schemas.)

Required Environment Variables

This server requires the following environment variables to connect to your SurrealDB instance:

• SURREALDB_URL: The WebSocket endpoint of your SurrealDB instance (e.g., ws://localhost:8000 or wss://cloud.surrealdb.com).
• SURREALDB_NS: The target Namespace.
• SURREALDB_DB: The target Database.
• SURREALDB_USER: The username for authentication (Root, NS, DB, or Scope user).
• SURREALDB_PASS: The password for the specified user.

Development

If you want to contribute to the development of this MCP server, follow these steps:

Local Development Setup

1. Clone the repository:

   Copy

   git clone https://github.com/nsxdavid/surrealdb-mcp-server.git
   cd surrealdb-mcp-server

2. Install dependencies:

   Copy

   npm install

3. Build the project:

   Copy

   npm run build

Running Locally

# Ensure required SURREALDB_* environment variables are set
npm run dev # (Note: dev script uses ts-node to run TypeScript directly)
# Or run the built version:
npm start

Testing

npm test # (Note: Tests need to be implemented)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Integration with n8n

You can integrate this SurrealDB MCP Server with n8n using the n8n-nodes-mcp community node.

NOTE: Currently only the self-hosted (Docker) version of n8n supports community nodes. There is no option for MCP Servers in the n8n cloud version (yet?).

Installation

1. Install the n8n-nodes-mcp package:

   Copy

   npm install n8n-nodes-mcp

2. Configure n8n to use the custom node:

   Add the following to your n8n configuration:

   Copy

   N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"

3. Configure the MCP node in n8n:

   • Add the "MCP" node to your workflow
   • Configure it to connect to your SurrealDB MCP Server
   • Select the desired operation (query, select, create, etc.)
   • Configure the operation parameters

For more details, visit the n8n-nodes-mcp GitHub repository.

Installation Guide

Which AI assistant are you using?

• 📝 Using Cline VS Code Extension? → Go to Cline Installation
• 🖥️ Using Claude Desktop App? → Go to Claude Installation
• 🤖 Using GitHub Copilot in VS Code? → Go to Copilot Installation
• 🦘 Using Roo Code in VS Code? → Go to Roo Code Installation
• 🌊 Using Windsurf? → Go to Windsurf Installation
• ⚡ Using Cursor? → Go to Cursor Installation
• 🔄 Using n8n? → Go to n8n Integration

📝 Cline Installation

One-Click Installation for Cline VS Code Extension

1. Install the package globally:

   Copy

   npm install -g surrealdb-mcp-server

2. Add to Cline settings:

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

   Add the following configuration:

   Copy

   {
     "mcpServers": {
       "surrealdb": {
         "command": "C:\\Program Files\\nodejs\\node.exe",
         "args": [
           "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\surrealdb-mcp-server\\build\\index.js"
         ],
         "env": {
           "SURREALDB_URL": "ws://localhost:8000",
           "SURREALDB_NS": "your_namespace",
           "SURREALDB_DB": "your_database",
           "SURREALDB_USER": "your_db_user",
           "SURREALDB_PASS": "your_db_password"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }

   Important: Replace YOUR_USERNAME with your actual Windows username in the path.

3. Restart VS Code

4. 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. Configure Claude Desktop to use the server:

   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:

   Copy

   {
     "mcpServers": {
       "surrealdb": {
         "command": "npx",
         "args": [
           "-y",
           "surrealdb-mcp-server"
         ],
         "env": {
           "SURREALDB_URL": "ws://localhost:8000",
           "SURREALDB_NS": "your_namespace",
           "SURREALDB_DB": "your_database",
           "SURREALDB_USER": "your_db_user",
           "SURREALDB_PASS": "your_db_password"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }

   Note: Using the npx command as shown above means the MCP client will automatically download and run the package from npm when needed. No manual installation is required.

2. Restart Claude Desktop App

3. 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. Create a workspace configuration file:

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

   Add the following configuration:

   Copy

   {
     "inputs": [
       {
         "type": "promptString",
         "id": "surrealdb-url",
         "description": "SurrealDB URL",
         "default": "ws://localhost:8000"
       },
       {
         "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": "npx",
         "args": [
           "-y",
           "surrealdb-mcp-server"
         ],
         "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}"
         }
       }
     }
   }

   Note: This configuration uses VS Code's input variables to securely prompt for and store your SurrealDB credentials.

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. Access MCP Settings:

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

2. Add the SurrealDB MCP Server configuration:

   Copy

   {
     "mcpServers": {
       "surrealdb": {
         "command": "C:\\Program Files\\nodejs\\node.exe",
         "args": [
           "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\surrealdb-mcp-server\\build\\index.js"
         ],
         "env": {
           "SURREALDB_URL": "ws://localhost:8000",
           "SURREALDB_NS": "your_namespace",
           "SURREALDB_DB": "your_database",
           "SURREALDB_USER": "your_db_user",
           "SURREALDB_PASS": "your_db_password"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }

   Important: Replace YOUR_USERNAME with your actual Windows username in the path.

3. Restart VS Code

4. 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 the package globally:

   Copy

   npm install -g surrealdb-mcp-server

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

3. Add the SurrealDB MCP Server configuration:

   Copy

   {
     "servers": [
       {
         "name": "surrealdb",
         "command": "node",
         "args": [
           "/path/to/global/node_modules/surrealdb-mcp-server/build/index.js"
         ],
         "env": {
           "SURREALDB_URL": "ws://localhost:8000",
           "SURREALDB_NS": "your_namespace",
           "SURREALDB_DB": "your_database",
           "SURREALDB_USER": "your_db_user",
           "SURREALDB_PASS": "your_db_password"
         }
       }
     ]
   }

   Note: Replace /path/to/global/node_modules with the actual path to your global node_modules directory.

4. Restart Windsurf

5. Verify Installation:

   • Open Cascade in Windsurf
   • You should see SurrealDB tools available in the tools list

⚡ Cursor Installation

Installation for Cursor

1. Install the package globally:

   Copy

   npm install -g surrealdb-mcp-server

2. Configure Cursor:

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

3. Add the SurrealDB MCP Server configuration:

   Copy

   {
     "name": "surrealdb",
     "command": "node",
     "args": [
       "/path/to/global/node_modules/surrealdb-mcp-server/build/index.js"
     ],
     "env": {
       "SURREALDB_URL": "ws://localhost:8000",
       "SURREALDB_NS": "your_namespace",
       "SURREALDB_DB": "your_database",
       "SURREALDB_USER": "your_db_user",
       "SURREALDB_PASS": "your_db_password"
     }
   }

   Note: Replace /path/to/global/node_modules with the actual path to your global node_modules directory.

4. Restart Cursor

5. Verify Installation:

   • Open Cursor Chat
   • You should see SurrealDB tools available in the tools list

Advanced Configuration

Using a Local Build

If you've cloned the repository or want to use a local build, you can use this configuration:

{
  "mcpServers": {
    "surrealdb": {
      "command": "node",
      "args": ["/path/to/your/surrealdb-mcp-server/build/index.js"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "your_namespace",
        "SURREALDB_DB": "your_database",
        "SURREALDB_USER": "your_db_user",
        "SURREALDB_PASS": "your_db_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

• Replace /path/to/your/surrealdb-mcp-server with the actual path where you cloned the repository
• Replace the environment variable values with your actual SurrealDB connection details

Troubleshooting

Common Issues

"Cannot find module" Error

If you see an error like "Cannot find module 'surrealdb-mcp-server'", try:

1. Verify the global installation: npm list -g surrealdb-mcp-server
2. Check the path in your configuration matches the actual installation path
3. Try reinstalling: npm install -g surrealdb-mcp-server

Connection Errors

If you see "Failed to connect to SurrealDB":

1. Verify SurrealDB is running: surreal start --log debug
2. Check your connection URL, namespace, database, and credentials
3. Ensure your SurrealDB instance is accessible from the path specified

Cline-Specific Issues

If the npx approach doesn't work with Cline:

1. Always use the global installation method for Cline
2. Specify the full path to node.exe and the installed package
3. Make sure to replace YOUR_USERNAME with your actual Windows username

License

MIT