README.md•14.9 kB
# SurrealDB MCP Server
<p align="center">
<img src="assets/images/sdblogo.png" width="256" alt="SurrealDB MCP Server Logo" />
</p>
<p align="center">
<a href="https://www.npmjs.com/package/surrealdb-mcp-server"><img src="https://img.shields.io/npm/v/surrealdb-mcp-server.svg" alt="npm version"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js Version"></a>
<a href="https://github.com/modelcontextprotocol/typescript-sdk"><img src="https://img.shields.io/badge/MCP%20SDK-%5E1.6.1-orange" alt="MCP SDK"></a>
</p>
A Model Context Protocol (MCP) server that provides a standardized interface for AI assistants to interact with a [SurrealDB](https://surrealdb.com/) database. This server enables AI systems to query and manipulate data within a configured SurrealDB instance.
> **Note for AI Assistants:** If you are an AI assistant (like Claude, Cline, Copilot, etc.) reading this documentation, please refer to the [llms-install.md](llms-install.md) file for detailed instructions specifically designed for you to help users install and configure this MCP server.
## Installation Guide
### Which AI assistant are you using?
- **📝 Using Cline VS Code Extension?** → [Go to Cline Installation](#cline-installation)
- **🖥️ Using Claude Desktop App?** → [Go to Claude Installation](#claude-installation)
- **🤖 Using GitHub Copilot in VS Code?** → [Go to Copilot Installation](#copilot-installation)
- **🦘 Using Roo Code in VS Code?** → [Go to Roo Code Installation](#roo-code-installation)
- **🌊 Using Windsurf?** → [Go to Windsurf Installation](#windsurf-installation)
- **⚡ Using Cursor?** → [Go to Cursor Installation](#cursor-installation)
- **🔄 Using [n8n](https://n8n.io/)?** → [Go to n8n Integration](#integration-with-n8n)
## Key Terms
- **MCP Server**: A server that implements the Model Context Protocol, allowing AI assistants to access external tools and resources
- **MCP Host**: The application (like VS Code with Cline or Claude Desktop) that connects to MCP servers
- **[SurrealDB](https://surrealdb.com/)**: A scalable, distributed, document-graph database with real-time capabilities
## Available Tools
The server exposes the following tools for interacting with SurrealDB:
- `query`: Execute a raw SurrealQL query.
- `select`: Select records from a table (all or by specific ID).
- `create`: Create a single new record in a table.
- `update`: Update a specific record, replacing its content.
- `delete`: Delete a specific record by ID.
- `merge`: Merge data into a specific record (partial update).
- `patch`: Apply JSON Patch operations to a specific record.
- `upsert`: Create a record if it doesn't exist, or update it if it does.
- `insert`: Insert multiple records into a table.
- `insertRelation`: Create a graph relation (edge) between two records.
*(Refer to the MCP host's tool listing for detailed input schemas.)*
## 📝 Cline Installation
### One-Click Installation for Cline VS Code Extension
1. **Install the package globally:**
```bash
npm install -g surrealdb-mcp-server
```
2. **Add to Cline settings:**
Edit the file at: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
Add the following configuration:
```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_namespace",
"SURREALDB_DB": "your_database",
"SURREALDB_USER": "your_db_user",
"SURREALDB_PASS": "your_db_password"
},
"disabled": false,
"autoApprove": []
}
}
}
```
> **Important:** Replace `YOUR_USERNAME` with your actual Windows username in the path.
3. **Restart VS Code**
4. **Verify Installation:**
- Open Cline in VS Code
- Ask Cline to "list available MCP servers"
- You should see "surrealdb" in the list
## 🖥️ Claude Installation
### Installation for Claude Desktop App
1. **Configure Claude Desktop to use the server:**
Edit the Claude Desktop App's MCP settings file:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
Add the following configuration:
```json
{
"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"
},
"disabled": false,
"autoApprove": []
}
}
}
```
> **Note:** Using the `npx` command as shown above means the MCP client will automatically download and run the package from npm when needed. No manual installation is required.
2. **Restart Claude Desktop App**
3. **Verify Installation:**
- Ask Claude to "list available MCP servers"
- You should see "surrealdb" in the list
## 🤖 Copilot Installation
### Installation for GitHub Copilot in VS Code
1. **Create a workspace configuration file:**
Create a file at: `.vscode/mcp.json` in your workspace
Add the following configuration:
```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}"
}
}
}
}
```
> **Note:** This configuration uses VS Code's input variables to securely prompt for and store your SurrealDB credentials.
2. **Verify Installation:**
- Open GitHub Copilot Chat in VS Code
- Select "Agent" mode from the dropdown
- Click the "Tools" button to see available tools
- You should see SurrealDB tools in the list
## 🦘 Roo Code Installation
### Installation for Roo Code in VS Code
1. **Access MCP Settings:**
Click the MCP icon in the top navigation of the Roo Code pane, then select "Edit MCP Settings" to open the configuration file.
2. **Add the SurrealDB MCP Server configuration:**
```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_namespace",
"SURREALDB_DB": "your_database",
"SURREALDB_USER": "your_db_user",
"SURREALDB_PASS": "your_db_password"
},
"disabled": false,
"autoApprove": []
}
}
}
```
> **Important:** Replace `YOUR_USERNAME` with your actual Windows username in the path.
3. **Restart VS Code**
4. **Verify Installation:**
- Open Roo Code in VS Code
- Click the MCP icon to see available servers
- You should see "surrealdb" in the list
## 🌊 Windsurf Installation
### Installation for Windsurf
1. **Install the package globally:**
```bash
npm install -g surrealdb-mcp-server
```
2. **Configure Windsurf:**
- Open Windsurf on your system
- Navigate to the Settings page
- Go to the Cascade tab
- Find the Model Context Protocol (MCP) Servers section
- Click on "View raw config" to open the configuration file (typically at `~/.codeium/windsurf/mcp_config.json`)
3. **Add the SurrealDB MCP Server configuration:**
```json
{
"servers": [
{
"name": "surrealdb",
"command": "node",
"args": [
"/path/to/global/node_modules/surrealdb-mcp-server/build/index.js"
],
"env": {
"SURREALDB_URL": "ws://localhost:8000",
"SURREALDB_NS": "your_namespace",
"SURREALDB_DB": "your_database",
"SURREALDB_USER": "your_db_user",
"SURREALDB_PASS": "your_db_password"
}
}
]
}
```
> **Note:** Replace `/path/to/global/node_modules` with the actual path to your global node_modules directory.
4. **Restart Windsurf**
5. **Verify Installation:**
- Open Cascade in Windsurf
- You should see SurrealDB tools available in the tools list
## ⚡ Cursor Installation
### Installation for Cursor
1. **Install the package globally:**
```bash
npm install -g surrealdb-mcp-server
```
2. **Configure Cursor:**
- Open Cursor
- Go to Settings > Cursor Settings
- Find the MCP Servers option and enable it
- Click on "Add New MCP Server"
3. **Add the SurrealDB MCP Server configuration:**
```json
{
"name": "surrealdb",
"command": "node",
"args": [
"/path/to/global/node_modules/surrealdb-mcp-server/build/index.js"
],
"env": {
"SURREALDB_URL": "ws://localhost:8000",
"SURREALDB_NS": "your_namespace",
"SURREALDB_DB": "your_database",
"SURREALDB_USER": "your_db_user",
"SURREALDB_PASS": "your_db_password"
}
}
```
> **Note:** Replace `/path/to/global/node_modules` with the actual path to your global node_modules directory.
4. **Restart Cursor**
5. **Verify Installation:**
- Open Cursor Chat
- You should see SurrealDB tools available in the tools list
## Required Environment Variables
This server requires the following environment variables to connect to your SurrealDB instance:
- `SURREALDB_URL`: The WebSocket endpoint of your SurrealDB instance (e.g., `ws://localhost:8000` or `wss://cloud.surrealdb.com`).
- `SURREALDB_NS`: The target Namespace.
- `SURREALDB_DB`: The target Database.
- `SURREALDB_USER`: The username for authentication (Root, NS, DB, or Scope user).
- `SURREALDB_PASS`: The password for the specified user.
## Troubleshooting
### Common Issues
#### "Cannot find module" Error
If you see an error like "Cannot find module 'surrealdb-mcp-server'", try:
1. Verify the global installation: `npm list -g surrealdb-mcp-server`
2. Check the path in your configuration matches the actual installation path
3. Try reinstalling: `npm install -g surrealdb-mcp-server`
#### Connection Errors
If you see "Failed to connect to SurrealDB":
1. Verify SurrealDB is running: `surreal start --log debug`
2. Check your connection URL, namespace, database, and credentials
3. Ensure your SurrealDB instance is accessible from the path specified
#### Cline-Specific Issues
If the npx approach doesn't work with Cline:
1. Always use the global installation method for Cline
2. Specify the full path to node.exe and the installed package
3. Make sure to replace YOUR_USERNAME with your actual Windows username
## Advanced Configuration
### Using a Local Build
If you've cloned the repository or want to use a local build, you can use this configuration:
```json
{
"mcpServers": {
"surrealdb": {
"command": "node",
"args": ["/path/to/your/surrealdb-mcp-server/build/index.js"],
"env": {
"SURREALDB_URL": "ws://localhost:8000",
"SURREALDB_NS": "your_namespace",
"SURREALDB_DB": "your_database",
"SURREALDB_USER": "your_db_user",
"SURREALDB_PASS": "your_db_password"
},
"disabled": false,
"autoApprove": []
}
}
}
```
- Replace `/path/to/your/surrealdb-mcp-server` with the actual path where you cloned the repository
- Replace the environment variable values with your actual SurrealDB connection details
## Development
If you want to contribute to the development of this MCP server, follow these steps:
### Local Development Setup
1. **Clone the repository:**
```bash
git clone https://github.com/nsxdavid/surrealdb-mcp-server.git
cd surrealdb-mcp-server
```
2. **Install dependencies:**
```bash
npm install
```
3. **Build the project:**
```bash
npm run build
```
### Running Locally
```bash
# Ensure required SURREALDB_* environment variables are set
npm run dev # (Note: dev script uses ts-node to run TypeScript directly)
# Or run the built version:
npm start
```
### Testing
```bash
npm test # (Note: Tests need to be implemented)
```
### Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## Integration with n8n
You can integrate this SurrealDB MCP Server with [n8n](https://n8n.io/) using the [n8n-nodes-mcp](https://github.com/nerding-io/n8n-nodes-mcp) community node.
**NOTE: Currently only the [self-hosted (Docker) version of n8n](https://docs.n8n.io/hosting/installation/docker/) supports community nodes. There is no option for MCP Servers in the n8n cloud version (yet?).**
### Installation
1. **Install the n8n-nodes-mcp package:**
```bash
npm install n8n-nodes-mcp
```
2. **Configure n8n to use the custom node:**
Add the following to your n8n configuration:
```bash
N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"
```
3. **Configure the MCP node in n8n:**
- Add the "MCP" node to your workflow
- Configure it to connect to your SurrealDB MCP Server
- Select the desired operation (query, select, create, etc.)
- Configure the operation parameters
For more details, visit the [n8n-nodes-mcp GitHub repository](https://github.com/nerding-io/n8n-nodes-mcp).
## License
MIT