# SurrealDB MCP > SurrealDB connects your AI agent directly to a multi-model database instance, letting you manage complex data operations using natural language conversation. Execute raw SurrealQL queries, create new records, update existing tables, and move data in or out of the system without ever leaving your chat interface. ## Overview - **Category:** databases - **Price:** Free - **Tags:** multi-model, surrealql, graph-database, relational-database, document-store, query-execution ## Description You can connect your private SurrealDB instance right into your AI client. Instead of writing boilerplate code or opening a separate database console, you talk to your agent about what you need done with your data—and it does it. Need to check if a record exists? Ask the agent. Want to pull every user ID from the 'users' table? Just prompt it. The MCP allows your AI client to run raw SurrealQL statements and handle all the tedious mechanics of database interaction, like creating records or exporting full datasets. If you access this via Vinkius, you get immediate control over a multi-model data layer right where you work. You manage everything from schema inspection using `get_health` to moving entire databases with tools like `import_sql` and `export_data`. It's about treating your database not as an isolated system, but as another service available in conversation. ## Tools ### create_specific_record Builds and inserts one new, defined record into a target table. ### delete_all Wipes every single record out of an entire specified table. ### delete_record Removes one specific, targeted record from a table. ### export_data Export data ### get_health Checks the current health and operational status of your SurrealDB instance. ### import_sql Ingests external data by running raw SurrealQL statements into the database. ### modify_all Overwrites or updates every single record in a table using merge operations. ### modify_record Updates one specific, targeted record with new data via merge operations. ### select_all Retrieves every single record that exists in an entire specified table. ### select_record Retrieves the details of a single, specified record by its unique ID. ### create_record Inserts a new record into a table and assigns it a randomly generated ID. ### execute_sql Runs arbitrary SurrealQL statements, allowing variables to be passed in via URL parameters. ### get_status Checks the web server status and operational uptime of your SurrealDB instance. ### update_all Applies updates to every single record in a table, overwriting existing data. ### update_record Updates one specific, targeted record with new information. ### get_version Returns the exact version number of the SurrealDB software currently running on the instance. ## Prompt Examples **Prompt:** ``` Check the health and version of my SurrealDB server. ``` **Response:** ``` I've checked your instance. The server is healthy (200 OK) and currently running SurrealDB version 2.1.0. ``` **Prompt:** ``` Select all records from the 'users' table. ``` **Response:** ``` I've retrieved all records from the 'users' table. There are 3 records: 'user:admin', 'user:john_doe', and 'user:jane_smith'. Would you like to see the details of a specific one? ``` **Prompt:** ``` Execute a SurrealQL query to find all posts where status is 'published'. ``` **Response:** ``` Running the SurrealQL query... I found 12 posts with the 'published' status. The most recent one is 'post:mcp-guide' created on 2023-10-27. ``` ## Capabilities ### Execute advanced queries Run complex, raw SurrealQL statements to pull specific data or run custom logic against the database. ### Manage record lifecycles Create new records with a random ID, update specific entries using `update_record`, or delete individual records when they are retired. ### Perform bulk data operations Modify all records in a table at once, or clear out an entire table entirely by selecting or deleting all data. ### Inspect database status and health Check the current operational status of your instance using `get_status` and verify its overall stability with `get_health`. ### Migrate and back up data Move information in or out of your database by importing raw SQL queries or exporting structured datasets. ## Use Cases ### Verifying database schema changes A data engineer needs to confirm if a new table structure is compatible with old scripts. Instead of running multiple manual checks, they prompt their agent to run `execute_sql` for various queries and check the system's response. ### Cleaning up test environments A backend developer finishes a feature branch and needs to wipe all generated user data. They simply ask the agent to use `delete_all` on the 'test_users' table, confirming cleanup without running SQL in a separate terminal. ### Ad-hoc reporting for PMs A product manager needs to see all posts from last quarter. They ask their agent to `select_all` records from the 'posts' table, getting an immediate list of IDs and metadata without involving the BI team. ### Onboarding new data sources A data scientist has a CSV dump that needs to populate a live database. They use `import_sql` through their agent, feeding the raw queries directly into the MCP for immediate ingestion. ## Benefits - You stop switching between tabs. Instead of opening a separate database console to test logic, you can execute raw SurrealQL statements using `execute_sql` directly within the chat interface. - Data maintenance is faster than manual clicks. Need to clean up old entries? Use `delete_all` or `modify_record` to manage records without writing complex scripts outside your environment. - Migration and auditing are simplified. If you need to move data, use `import_sql` to load queries or grab a full dataset using `export_data`, all prompted naturally. - You get immediate visibility into the system. Use `get_status` and `get_health` to confirm your instance is up and running before starting any critical tasks. - The process of getting data out is straightforward. You can select everything in a table with `select_all`, or just pull one specific piece using `select_record`, then pass that result on. ## How It Works The bottom line is that you talk to your AI client like it’s an extension of your terminal, giving it direct data access. 1. First, subscribe to this MCP on Vinkius and provide the necessary SurrealDB URL along with your credentials (namespace, database name, and authentication key). 2. Next, connect your preferred AI client—like Cursor or Claude—to the configured endpoint. Your agent now recognizes the full set of available data tools. 3. Finally, simply ask your agent to perform a task, such as 'Select all users who haven't logged in this month.' The MCP executes the necessary database calls and returns the structured results. ## Frequently Asked Questions **How do I run a query using SurrealDB MCP?** You use the `execute_sql` tool by prompting your agent with the specific SurrealQL statement. The system executes it against your live database instance and returns structured results. **Can I delete all data from a table using SurrealDB MCP?** Yes, you can use the `delete_all` tool to wipe every record in an entire table. Be careful with this action; it's irreversible. **What is the difference between create_record and execute_sql?** `create_record` generates a new record with a random ID for simple inserts. `execute_sql` lets you run any complex, raw SurrealQL statement, giving you full control over the query logic. **Does this MCP handle data migration?** Yes, it handles migration using tools like `import_sql`, which allows you to feed external SQL queries into your instance for ingestion. **What if I only need one specific record? Should I use select_record or execute_sql?** If you know the exact ID, use `select_record`. If you need to filter records using complex criteria (like 'all active users'), it's better to wrap that logic in an `execute_sql` query.