nsxdavid surrealdb mcp server

nsxdavid surrealdb mcp server avatar

by nsxdavid

What is nsxdavid 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?

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:

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

    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

โšก Cursor Installation

Installation for Cursor

  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

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:

    • 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

Leave a Comment

Frequently Asked Questions

What is MCP?

MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications, providing a standardized way to connect AI models to different data sources and tools.

What are MCP Servers?

MCP Servers are lightweight programs that expose specific capabilities through the standardized Model Context Protocol. They act as bridges between LLMs like Claude and various data sources or services, allowing secure access to files, databases, APIs, and other resources.

How do MCP Servers work?

MCP Servers follow a client-server architecture where a host application (like Claude Desktop) connects to multiple servers. Each server provides specific functionality through standardized endpoints and protocols, enabling Claude to access data and perform actions through the standardized protocol.

Are MCP Servers secure?

Yes, MCP Servers are designed with security in mind. They run locally with explicit configuration and permissions, require user approval for actions, and include built-in security features to prevent unauthorized access and ensure data privacy.

Related MCP Servers

PostgreSQL MCP Server avatar

PostgreSQL MCP Server

A Model Context Protocol server that provides read-only access to PostgreSQL databases. This server enables LLMs to inspect database schemas and execute read-only queries.

databasepostgresqlcommunity
chrisdoc hevy mcp avatar

chrisdoc hevy mcp

mcp
sylphlab pdf reader mcp avatar

sylphlab pdf reader mcp

An MCP server built with Node.js/TypeScript that allows AI agents to securely read PDF files (local or URL) and extract text, metadata, or page counts. Uses pdf-parse.

pdf-parsetypescriptnodejs
aashari mcp server atlassian bitbucket avatar

aashari mcp server atlassian bitbucket

Node.js/TypeScript MCP server for Atlassian Bitbucket. Enables AI systems (LLMs) to interact with workspaces, repositories, and pull requests via tools (list, get, comment, search). Connects AI directly to version control workflows through the standard MCP interface.

atlassianrepositorymcp
aashari mcp server atlassian confluence avatar

aashari mcp server atlassian confluence

Node.js/TypeScript MCP server for Atlassian Confluence. Provides tools enabling AI systems (LLMs) to list/get spaces & pages (content formatted as Markdown) and search via CQL. Connects AI seamlessly to Confluence knowledge bases using the standard MCP interface.

atlassianmcpconfluence
prisma prisma avatar

prisma prisma

Next-generation ORM for Node.js & TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB

cockroachdbgomcp
Zzzccs123 mcp sentry avatar

Zzzccs123 mcp sentry

mcp sentry for typescript sdk

mcptypescript
zhuzhoulin dify mcp server avatar

zhuzhoulin dify mcp server

mcp
zhongmingyuan mcp my mac avatar

zhongmingyuan mcp my mac

mcp
zhixiaoqiang desktop image manager mcp avatar

zhixiaoqiang desktop image manager mcp

MCP ๆœๅŠกๅ™จ๏ผŒ็”จไบŽ็ฎก็†ๆกŒ้ขๅ›พ็‰‡ใ€ๆŸฅ็œ‹่ฏฆๆƒ…ใ€ๅŽ‹็ผฉใ€็งปๅŠจ็ญ‰๏ผˆๅฎŒๅ…จ่ฎฉTraeๅฎž็Žฐ๏ผ‰

mcp

Submit Your MCP Server

Share your MCP server with the community

Submit Now