queryLABSCO SUMMARY
Typed tools over raw SurrealQL, including the graph edges SurrealDB is built for.
You get both routes: raw query for anything, and typed select/create/update/delete when you want the operation to be explicit rather than a string. insertRelation is the SurrealDB-specific one worth noting — it creates a graph edge between records, which is the feature that separates SurrealDB from a plain document store. Access is whatever the configured database user has.
What it is
A server that gives an assistant a standardized interface to a configured SurrealDB instance — raw queries plus typed CRUD and graph operations.
What you get
- query runs a raw SurrealQL query; select reads records from a table, all or by ID
- create, update, delete and merge cover the record lifecycle, with merge doing a partial update
- patch applies JSON Patch operations; upsert creates or updates in one call
- insert adds multiple records at once
- insertRelation creates a graph edge between two records
Requirements
A running SurrealDB instance and five environment variables — SURREALDB_URL, SURREALDB_NS, SURREALDB_DB, SURREALDB_USER and SURREALDB_PASS. Node.js >=18.0.0. Run it with npx and the surrealdb-mcp-server package, which downloads and runs it on demand with no manual install.
Setup effort
One command plus credentials — npm install -g surrealdb-mcp-server, then supply credentials
USE CASES
01
Running a query against your database
Send raw SurrealQL and read the results in the conversation.
02
Reading records without writing a query
Select from a table, all of it or one record by ID.
03
Updating part of a record
Merge new fields in, or apply JSON Patch operations for precise edits.
04
Loading a batch of records
Insert many at once instead of one create per row.
05
Connecting two records in the graph
Create an edge between them with the relation tool.
10 tools
Listed in project docs. Your client may show a different list.
selectcreateupdatedeletemergepatchupsertinsertinsertRelationBEFORE YOU INSTALL
What to know first
Tools you get
10 tools named in the project's documentation.
Requires
- Node.js >= 18
- A running SurrealDB instance
- SURREALDB_URL, SURREALDB_NS, SURREALDB_DB, SURREALDB_USER and SURREALDB_PASS set in your client configuration
INSTALLATION
Connect your client
Server setup
TERMINAL
npm install -g surrealdb-mcp-serverMCP Clients
Cline, Roo Code
Windows only, as the project writes it — <YOUR_USERNAME> is your Windows username.
JSON
{
"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_SURREALDB_NS>",
"SURREALDB_DB": "<YOUR_SURREALDB_DB>",
"SURREALDB_USER": "<YOUR_SURREALDB_USER>",
"SURREALDB_PASS": "<YOUR_SURREALDB_PASS>"
},
"disabled": false,
"autoApprove": []
}
}
}Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"surrealdb": {
"command": "npx",
"args": [
"-y",
"surrealdb-mcp-server"
],
"env": {
"SURREALDB_URL": "ws://localhost:8000",
"SURREALDB_NS": "<YOUR_SURREALDB_NS>",
"SURREALDB_DB": "<YOUR_SURREALDB_DB>",
"SURREALDB_USER": "<YOUR_SURREALDB_USER>",
"SURREALDB_PASS": "<YOUR_SURREALDB_PASS>"
},
"disabled": false,
"autoApprove": []
}
}
}VS Code
VS CODE · JSON
{
"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}"
}
}
}
}Windsurf, Cursor
JSON
{
"mcpServers": {
"surrealdb": {
"command": "node",
"args": [
"<YOUR_PATH_TO_GLOBAL>/node_modules/surrealdb-mcp-server/build/index.js"
],
"env": {
"SURREALDB_URL": "ws://localhost:8000",
"SURREALDB_NS": "<YOUR_SURREALDB_NS>",
"SURREALDB_DB": "<YOUR_SURREALDB_DB>",
"SURREALDB_USER": "<YOUR_SURREALDB_USER>",
"SURREALDB_PASS": "<YOUR_SURREALDB_PASS>"
}
}
}
}n8n
Install the n8n-nodes-mcp package:
N8N · TERMINAL
npm install n8n-nodes-mcpAdd the following to your n8n configuration:
FILE
N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"In n8n, create a Command-line Based Transport (STDIO) credential for the MCP Client node: Command npx, Arguments -y surrealdb-mcp-server, and Environment Variables SURREALDB_URL, SURREALDB_NS, SURREALDB_DB, SURREALDB_USER and SURREALDB_PASS in NAME=VALUE format.
Add the MCP node to your workflow and select the operation you need (query, select, create, etc.).
