surrealdb-mcp-server

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