SurrealDB MCP Server
Connect your AI models to your favorite SurrealDB database, and let the LLMs do all your work for you.
What is SurrealDB MCP Server?
SurrealDB MCP Server is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to connect your ai models to your favorite surrealdb database, and let the llms do all your work for you.
Connect your AI models to your favorite SurrealDB database, and let the LLMs do all your work for you.
This server falls under the Databases category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Connect your AI models to your favorite SurrealDB database,
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx surrealdb-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use SurrealDB MCP Server
The SurrealDB MCP Server bridges AI assistants to SurrealDB, a multi-model database that supports graph, document, and relational data. It exposes ten database operation tools — from raw SurrealQL queries to graph edge creation — allowing LLMs to read, write, and manipulate SurrealDB records through natural language. It works with Claude Desktop, Cline, Cursor, Windsurf, and other MCP-compatible clients.
Prerequisites
- A running SurrealDB instance (local or remote) accessible via WebSocket
- SurrealDB namespace, database, username, and password credentials
- Node.js 18 or higher, or the ability to run npx
- An MCP-compatible client such as Claude Desktop, Cline, or Cursor
Start a SurrealDB instance
Run SurrealDB locally using the official Docker image or binary. The MCP server connects via WebSocket, so ensure SurrealDB is listening on a WebSocket-accessible address.
docker run --rm -p 8000:8000 surrealdb/surrealdb:latest start --log trace --user root --pass root memoryInstall the MCP server globally (optional)
You can install the package globally for faster startup, or rely on npx to download it on demand. Global installation avoids network calls on every restart.
npm install -g surrealdb-mcp-serverAdd the server to your MCP client config
Edit your claude_desktop_config.json (on macOS at ~/Library/Application Support/Claude/claude_desktop_config.json) to register the server with connection credentials.
{
"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"
}
}
}
}Restart your MCP client
Restart Claude Desktop or your IDE to load the new server configuration. The client will spawn the surrealdb-mcp-server process and establish the database connection on startup.
Test with a query
Ask your AI assistant to list tables or run a SurrealQL query. The server exposes the query tool for raw SurrealQL and the select tool for record retrieval.
SurrealDB MCP Server Examples
Client configuration
Claude Desktop configuration with all five required environment variables for SurrealDB connection.
{
"mcpServers": {
"surrealdb": {
"command": "npx",
"args": ["-y", "surrealdb-mcp-server"],
"env": {
"SURREALDB_URL": "ws://localhost:8000",
"SURREALDB_NS": "production",
"SURREALDB_DB": "myapp",
"SURREALDB_USER": "admin",
"SURREALDB_PASS": "secret"
}
}
}
}Prompts to try
Natural language prompts that exercise the ten database operation tools exposed by this server.
- "Run a SurrealQL query to list all records in the users table"
- "Create a new user record with name John Doe and email [email protected]"
- "Select the user record with ID users:123"
- "Create a graph edge between users:alice and users:bob with relationship type follows"
- "Delete all records in the sessions table older than 30 days"Troubleshooting SurrealDB MCP Server
Connection refused or WebSocket error on startup
Verify SurrealDB is running and accessible at the SURREALDB_URL you configured. For Docker deployments, ensure the port is mapped correctly. Use ws:// for local connections and wss:// for TLS-encrypted remote connections.
Authentication failed with provided credentials
Double-check SURREALDB_USER and SURREALDB_PASS match the credentials your SurrealDB instance was started with. Also verify that SURREALDB_NS and SURREALDB_DB exist — SurrealDB will reject connections to namespaces or databases that have not been created.
npx command hangs or fails to download the package
Install the package globally first with npm install -g surrealdb-mcp-server and change the command in your config to surrealdb-mcp-server with an empty args array. This avoids network dependency on every client restart.
Frequently Asked Questions about SurrealDB MCP Server
What is SurrealDB MCP Server?
SurrealDB MCP Server is a Model Context Protocol (MCP) server that connect your ai models to your favorite surrealdb database, and let the llms do all your work for you. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install SurrealDB MCP Server?
Follow the installation instructions on the SurrealDB MCP Server GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with SurrealDB MCP Server?
SurrealDB MCP Server works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is SurrealDB MCP Server free to use?
Yes, SurrealDB MCP Server is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
SurrealDB MCP Server Alternatives — Similar Databases Servers
Looking for alternatives to SurrealDB MCP Server? Here are other popular databases servers you can use with Claude, Cursor, and VS Code.
Excelize
★ 20.6kGo language library for reading and writing Microsoft Excel™ (XLAM / XLSM / XLSX / XLTM / XLTX) spreadsheets
MCP Toolbox for Databases
★ 15.3kOpen source MCP server specializing in easy, fast, and secure tools for Databases.
DBHub
★ 2.8kA universal database gateway MCP server that enables AI assistants to connect to and query multiple databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite) with support for schema exploration, SQL execution, and secure connections via SSH tunnels.
Tabularis
★ 2.1kA lightweight, cross-platform database client for developers. Supports MySQL, PostgreSQL and SQLite. Hackable with plugins. Built for speed, security, and aesthetics.
Postgres AI Guide
★ 1.7kMCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.
Anyquery
★ 1.7k🏎️ 🏠 ☁️ - Query more than 40 apps with one binary using SQL. It can also connect to your PostgreSQL, MySQL, or SQLite compatible database. Local-first and private by design.
Browse More Databases MCP Servers
Explore all databases servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up SurrealDB MCP Server in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use SurrealDB MCP Server?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.