SurrealDB MCP Server

What is SurrealDB MCP Server?

A Model Context Protocol server that provides a standardized interface for AI assistants to query and manipulate data within a SurrealDB database. It enables AI systems to perform CRUD operations and run SurrealQL queries against a configured SurrealDB instance.

How to use SurrealDB MCP Server?

Install globally via npm (npm install -g surrealdb-mcp-server) or run on-demand with npx -y surrealdb-mcp-server. Configure the server by setting five environment variables (SURREALDB_URL, SURREALDB_NS, SURREALDB_DB, SURREALDB_USER, SURREALDB_PASS) in your MCP host’s settings file, then restart the host and verify the server appears in the tool list.

Key features of SurrealDB MCP Server

• Execute raw SurrealQL queries via the query tool.
• Perform CRUD operations: select, create, update, delete, merge.
• Use advanced operations: patch, upsert, insert, insertRelation.
• Handles graph relation creation between records.
• Connects to local or cloud SurrealDB instances via WebSocket.

Use cases of SurrealDB MCP Server

• Allow an AI coding assistant to create, read, update, and delete records in a SurrealDB database.
• Enable an AI chatbot to run custom SurrealQL queries for data analysis.
• Let an AI agent insert bulk records or define graph edges between entities.

FAQ from SurrealDB MCP Server

What environment variables are required?

The server needs SURREALDB_URL, SURREALDB_NS, SURREALDB_DB, SURREALDB_USER, and SURREALDB_PASS to connect to a SurrealDB instance.

How do I verify the server is installed correctly?

Ask your MCP host (e.g., Claude, Cline) to “list available MCP servers” – “surrealdb” should appear. If not, check your configuration path and environment variables.

What if I see a “Cannot find module” error?

Ensure the package is globally installed (npm list -g surrealdb-mcp-server) and that the path in your MCP settings matches the actual installation location. Reinstall if needed.

Why am I getting a connection error?

Verify that SurrealDB is running (surreal start --log debug) and that the URL, namespace, database, and credentials are correct and reachable from the server host.

Can I use this server without a global install?

Yes. Using npx -y surrealdb-mcp-server as the command in your MCP configuration automatically downloads and runs the package without a permanent global install.