surrealdb-mcp-server
Advanced tools
A Model Context Protocol (MCP) server that provides a standardized interface for AI assistants to interact with a SurrealDB database.
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.
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.)
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_USERNAMEwith your actual Windows username in the path.
Restart VS Code
Verify Installation:
Configure Claude Desktop to use the server:
Edit the Claude Desktop App's MCP settings file:
%APPDATA%\Claude\claude_desktop_config.json~/Library/Application Support/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonAdd 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
npxcommand 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:
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:
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_USERNAMEwith your actual Windows username in the path.
Restart VS Code
Verify Installation:
Install the package globally:
npm install -g surrealdb-mcp-server
Configure Windsurf:
~/.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_moduleswith the actual path to your global node_modules directory.
Restart Windsurf
Verify Installation:
Install the package globally:
npm install -g surrealdb-mcp-server
Configure Cursor:
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_moduleswith the actual path to your global node_modules directory.
Restart Cursor
Verify Installation:
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.If you see an error like "Cannot find module 'surrealdb-mcp-server'", try:
npm list -g surrealdb-mcp-servernpm install -g surrealdb-mcp-serverIf you see "Failed to connect to SurrealDB":
surreal start --log debugIf the npx approach doesn't work with Cline:
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": []
}
}
}
/path/to/your/surrealdb-mcp-server with the actual path where you cloned the repositoryIf you want to contribute to the development of this MCP server, follow these steps:
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
# 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
npm test # (Note: Tests need to be implemented)
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
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?).
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:
For more details, visit the n8n-nodes-mcp GitHub repository.
MIT
FAQs
A Model Context Protocol (MCP) server that provides a standardized interface for AI assistants to interact with a SurrealDB database.
The npm package surrealdb-mcp-server receives a total of 23 weekly downloads. As such, surrealdb-mcp-server popularity was classified as not popular.
We found that surrealdb-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
As vulnerability data bottlenecks grow, the federal government is formally investigating NIST’s handling of the National Vulnerability Database.
Research
Security News
Socket’s Threat Research Team has uncovered 60 npm packages using post-install scripts to silently exfiltrate hostnames, IP addresses, DNS servers, and user directories to a Discord-controlled endpoint.
Security News
TypeScript Native Previews offers a 10x faster Go-based compiler, now available on npm for public testing with early editor and language support.