SurrealDB Database

by nsxdavid

8 stars
196 downloads
Not rated
GitHub

About

A Model Context Protocol (MCP) server that provides a standardized interface for AI assistants to interact with a SurrealDB database.

Details

Author
nsxdavid
Repository
nsxdavid/surrealdb-mcp-server
GitHub stars
8
Downloads
196
License
Other
Categories
Database, Developer Tools, Search, Workplace, Productivity, AI, Other

Jump to

- Execute raw SurrealQL queries via the query tool.
- Perform CRUD operations: select, create, update, delete, merge.
- Use advanced operations: patch, upsert, insert, insertRelation.
- Handles graph relation creation between records.
- Connects to local or cloud SurrealDB instances via WebSocket.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name SurrealDB Database
    Command (node, npx, python, etc.) npx
    Arguments
    • Argument 1 -y
    • Argument 2 surrealdb-mcp-server
    Environment
    • SURREALDB_DB your_database
    • SURREALDB_NS your_namespace
    • SURREALDB_URL ws://localhost:8000
    • SURREALDB_PASS your_db_password
    • SURREALDB_USER your_db_user

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

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:

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

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:
- Open Cline in VS Code
- Ask Cline to "list available MCP servers"
- You should see "surrealdb" in the list

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:

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

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

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:
- Open Roo Code in VS Code
- Click the MCP icon to see available servers
- You should see "surrealdb" in the list

1. Install the package globally:

   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:

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

1. Install the package globally:

   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:

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

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.

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

```bash

npm run dev # (Note: dev script uses ts-node to run TypeScript directly)

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.

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

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

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

SurrealDB MCP Server

<p align="center">
SurrealDB MCP Server Logo
</p>

<p align="center">
<a href="https://www.npmjs.com/package/surrealdb-mcp-server">npm version</a>
<a href="https://opensource.org/licenses/MIT">License: MIT</a>
<a href="https://nodejs.org/">Node.js Version</a>
<a href="https://github.com/modelcontextprotocol/typescript-sdk">MCP SDK</a>
</p>

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

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

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

…

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

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

More like this

Similar MCP servers you might find useful

Browse category

Git

A Model Context Protocol (MCP) server that provides tools for LLMs to read, search, and manipulate Git repositories. It enables automated repository…

88.1k
Developer Tools