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.

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

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

📝 Cline Installation

One-Click Installation for Cline VS Code Extension

1. Install the package globally:

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:

{
     "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:

🖥️ Claude Installation

Installation for Claude Desktop App

1. Configure Claude Desktop to use the server:

Edit the Claude Desktop App's MCP settings file:

Add the following configuration:

{
     "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:

🤖 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:

{
     "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:

🦘 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:

{
     "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:

🌊 Windsurf Installation

Installation for Windsurf

1. Install the package globally:

npm install -g surrealdb-mcp-server

2. Configure Windsurf:

3. Add the SurrealDB MCP Server configuration:

{
     "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:

⚡ Cursor Installation

Installation for Cursor

1. Install the package globally:

npm install -g surrealdb-mcp-server

2. Configure Cursor:

3. Add the SurrealDB MCP Server configuration:

{
     "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:

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.

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

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

Development

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

Local Development Setup

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the project:

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:

npm install n8n-nodes-mcp

2. Configure n8n to use the custom node:

Add the following to your n8n configuration:

N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"

3. Configure the MCP node in n8n:

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

License

MIT