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

Install the package globally:
```
npm install -g surrealdb-mcp-server
```

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.

Restart VS Code
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

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:

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

Restart Claude Desktop App
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

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.

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

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.

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.

Restart VS Code
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 the package globally:
```
npm install -g surrealdb-mcp-server
```
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 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.

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

⚡ Cursor Installation

Installation for Cursor

Install the package globally:
```
npm install -g surrealdb-mcp-server
```
Configure Cursor:
- Open Cursor
- Go to Settings > Cursor Settings
- Find the MCP Servers option and enable it
- Click on "Add New MCP Server"

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.

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

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:

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

Connection Errors

If you see "Failed to connect to SurrealDB":

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

Cline-Specific Issues

If the npx approach doesn't work with Cline:

Always use the global installation method for Cline
Specify the full path to node.exe and the installed package
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

Clone the repository:

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

Install dependencies:
```
npm install
```
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

Install the n8n-nodes-mcp package:
```
npm install n8n-nodes-mcp
```
Configure n8n to use the custom node:

Add the following to your n8n configuration:
```
N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"
```
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.

License

MIT