SurrealDB itself is open source and free to self-host, and the surrealmcp server is published under the Business Source License 1.1, free to run for your own use. You only pay if you choose a managed SurrealDB Cloud instance.

Does it support remote/OAuth?

The server runs locally over stdio, HTTP, or a Unix socket and connects to local or remote SurrealDB instances with URL and credential env vars. It supports bearer-token (JWT) authentication on its HTTP transport and manages SurrealDB Cloud access via cloud tokens; there is no hosted OAuth endpoint.

Can the agent write data?

Yes. Alongside query and select, the server exposes insert, create, upsert, update, delete, and relate tools, so an agent can fully mutate data. Scope the connecting user's permissions to limit what it can change.

SurrealDB MCP server

OfficialSurrealDBConfig last verified Jun 1, 2026

SurrealDB's official MCP server lets agents query and mutate a SurrealDB instance with SurrealQL and manage SurrealDB Cloud.

SurrealMCP is the official Model Context Protocol server for SurrealDB, the multi-model database that unifies document, graph, relational, and vector data behind a single query language. It gives an AI agent first-class access to a SurrealDB instance: it can run arbitrary SurrealQL with the query tool, perform structured select, insert, create, upsert, update, delete, and relate operations, and traverse the connection model by switching the active namespace and database. Because SurrealDB speaks documents, graphs, and vectors through one protocol, an agent can model and explore richly connected data without juggling separate engines, making it a strong backend for agent memory, knowledge graphs, and application data alike.

The server is distributed as a Rust binary and is most easily run via the official Docker image (docker run --rm -i surrealdb/surrealmcp:latest start) or built from source with cargo, communicating over stdio, HTTP, or a Unix socket. It connects to local engines (in-memory, file, RocksDB) or remote instances over ws:// and http://, authenticating with SURREALDB_URL plus namespace, database, user, and password environment variables. It also exposes a set of SurrealDB Cloud management tools — list organizations and instances, create, pause, resume, and check the status of cloud instances — so the same agent can provision and operate managed SurrealDB Cloud alongside reading and writing data.

Quick install

Copy-paste configs are provided for all 8 supported clients. Pick your client below.

Add to ~/.claude.json

~/.claude.json

json

{
  "mcpServers": {
    "surrealdb": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "surrealdb/surrealmcp:latest",
        "start"
      ],
      "env": {
        "SURREALDB_URL": "<SURREALDB_URL>",
        "SURREALDB_NS": "<SURREALDB_NS>",
        "SURREALDB_DB": "<SURREALDB_DB>",
        "SURREALDB_USER": "<SURREALDB_USER>",
        "SURREALDB_PASS": "<SURREALDB_PASS>"
      }
    }
  }
}

Or via CLI

bash

claude mcp add surrealdb -- docker run --rm -i surrealdb/surrealmcp:latest start

Step-by-step guides

Available tools

Tool	Description
query	Runs an arbitrary SurrealQL statement against the connected instance, with parameter binding.
select	Selects records from a table or by record ID.
insert	Inserts one or more records into a table.
create	Creates a single record with the given content.
upsert	Inserts a record or updates it if it already exists.
update	Updates existing records with new content.
delete	Deletes records from a table or by record ID.
relate	Creates a graph edge relating two records.
connect_endpoint	Connects to a SurrealDB endpoint at runtime.
disconnect_endpoint	Disconnects from the current SurrealDB endpoint.
use_namespace	Sets the active namespace for subsequent operations.
use_database	Sets the active database for subsequent operations.
list_namespaces	Lists the namespaces available on the instance.
list_databases	Lists the databases within the current namespace.
list_cloud_organizations	Lists the SurrealDB Cloud organizations the credentials can access.
list_cloud_instances	Lists the SurrealDB Cloud instances in an organization.
create_cloud_instance	Provisions a new SurrealDB Cloud instance.
pause_cloud_instance	Pauses a running SurrealDB Cloud instance.
resume_cloud_instance	Resumes a paused SurrealDB Cloud instance.
get_cloud_instance_status	Reports the current status of a SurrealDB Cloud instance.

Required configuration

SURREALDB_URLRequired
Connection URL for the SurrealDB instance (ws://, http://, memory, file, rocksdb, or a SurrealDB Cloud endpoint).
SURREALDB_NSOptional
Default namespace to operate in.
SURREALDB_DBOptional
Default database to operate in.
SURREALDB_USEROptional
Username used to authenticate with the instance.
SURREALDB_PASSOptional
Password for the SurrealDB user.
SURREAL_MCP_CLOUD_ACCESS_TOKENOptional
Access token for SurrealDB Cloud management operations. Optional.
SURREAL_MCP_RATE_LIMIT_RPSOptional
Caps the requests-per-second the server will issue. Optional.

What you can do with it

Give an agent a multi-model data layer

Let an agent create records, relate them as a graph, and run SurrealQL to answer questions across documents, relations, and vectors in one place, without standing up separate databases for each model.

Provision and operate SurrealDB Cloud

Use the cloud tools to list organizations and instances and to create, pause, resume, or check the status of a managed SurrealDB Cloud instance, so the agent can spin up and tear down environments on demand.

FAQ

Is it free?: SurrealDB itself is open source and free to self-host, and the surrealmcp server is published under the Business Source License 1.1, free to run for your own use. You only pay if you choose a managed SurrealDB Cloud instance.
Does it support remote/OAuth?: The server runs locally over stdio, HTTP, or a Unix socket and connects to local or remote SurrealDB instances with URL and credential env vars. It supports bearer-token (JWT) authentication on its HTTP transport and manages SurrealDB Cloud access via cloud tokens; there is no hosted OAuth endpoint.
Can the agent write data?: Yes. Alongside query and select, the server exposes insert, create, upsert, update, delete, and relate tools, so an agent can fully mutate data. Scope the connecting user's permissions to limit what it can change.

← Browse all databases servers