Surrealdb MCP Server

🚀 SurrealDB MCP Server Documentation

SurrealDB MCP Server is a powerful tool that simplifies the management and interaction with SurrealDB instances. It provides a convenient way to configure and run multiple servers, making it easier to integrate SurrealDB into your projects.

🚀 Quick Start

Basic Configuration Example

Here is a basic configuration example for the mcp.json file:

{
  "mcpServers": {
    "surrealdb": {
      "command": "node",
      "args": ["$(npm prefix)/bin/surrealdb-mcp-server"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "my-namespace",
        "SURREALDB_DB": "my-database",
        "SURREALDB_USER": "root",
        "SURREALDB_PASS": "password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Configuration Parameter Explanation

• command: Specifies the executable file path for running the command.
• args: A list of parameters passed to the command.
• env: Sets environment variables to connect to the SurrealDB instance.
• disabled: Whether to disable this MCP server (default is false).
• autoApprove: A list of operations to be automatically approved.

📦 Installation

Install with npm

Install surrealdb-mcp-server globally on your system:

npm install -g surrealdb-mcp-server

Run with npx

Run directly using npx without installation:

npx surrealdb-mcp-server

💻 Usage Examples

Integrate into a Project

Create an mcp.json file in the root directory of your project and add multiple MCP server configurations as needed. For example:

cd your-project
npm init -y # If there is no package.json yet

Then import and use the MCP server in your code:

const { MCP } = require('surrealdb-mcp-server');
// Or use ES6 module syntax:
import { MCP } from 'surrealdb-mcp-server';

Create an MCP Client

Here is a simple example of a client implementation:

const { createMCPClient } = require('surrealdb-mcp-server');

async function main() {
  const client = await createMCPClient({
    serverName: 'surrealdb',
    command: 'node',
    args: ['$(npm prefix)/bin/surrealdb-mcp-server'],
    env: {
      SURREALDB_URL: 'ws://localhost:8000',
      SURREALDB_NS: 'my-namespace',
      SURREALDB_DB: 'my-database',
      SURREALDB_USER: 'root',
      SURREALDB_PASS: 'password'
    }
  });

  // Perform database operations
  await client.execute('SELECT * FROM users');
}

main().catch(console.error);

📚 Documentation

Environment Variable Configuration

The following are the environment variables that need to be set and their meanings:

Troubleshooting

"Cannot find module" Error

If you encounter an error like "Cannot find module 'surrealdb-mcp-server'", try the following steps:

1. Verify the global installation: npm list -g surrealdb-mcp-server
2. Check if the path in the configuration matches the actual installation path.
3. Reinstall: npm install -g surrealdb-mcp-server

Connection Issues

If you encounter a "Failed to connect to SurrealDB" error, check the following:

1. Ensure that the SurrealDB instance is running.
2. Check if the network connection is normal.
3. Verify that the environment variables are set correctly.

Usage Scenarios

Local Development

When using the MCP server in a local project, you can add it as a development dependency to package.json:

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "start": "surrealdb-mcp-server"
  },
  "devDependencies": {
    "surrealdb-mcp-server": "^1.0.0"
  }
}

Then run:

npm install
npm start

Production Environment

When using it in a production environment, it is recommended to run the MCP server as a service. For example, on a Linux system, you can register it as a system service.

Advanced Configuration

Batch Operation Support

The MCP server supports batch operation requests, and you can extend the functionality as needed:

// Add multiple server configurations in mcp.json
{
  "mcpServers": {
    "surrealdb1": { ... },
    "surrealdb2": { ... }
  }
}

Logging

The MCP server supports detailed logging functionality, and you can customize the log output format and level:

// Add logging configuration in mcp.json
{
  "logging": {
    "level": "debug",
    "outputFile": "./mcp.log"
  }
}

⚠️ Other Notes

Permission Issues

On some systems, you may need to run the MCP server with administrator privileges. For example, on Windows, use the runas command:

runas /user:Administrator npm start

Performance Optimization

To achieve optimal performance, ensure that your SurrealDB instance and MCP server configurations are fully supported by the hardware resources, including sufficient memory and CPU resources.

👋 Conclusion

Thank you for choosing the SurrealDB MCP Server. If you have any questions or suggestions during use, please feel free to contact our technical support team.