Nsxdavid Surrealdb MCP Server

🚀 Guide to the SurrealDB MCP Server

This guide provides a comprehensive overview of installing, configuring, and using the SurrealDB MCP Server. It also includes troubleshooting tips, advanced usage scenarios, best practices, and contribution guidelines.

📦 Installation

Global Installation (Recommended)

To globally install the SurrealDB MCP Server, run the following command in your terminal:

npm install -g surrealdb-mcp-server

npx Method (For Testing Only)

You can also quickly run the server using npx:

npx surrealdb-mcp-server

🛠️ Configuration

The MCP Server can be configured via a configuration file or command-line arguments. Here's an example of the default configuration file:

{
  "mcpServers": {
    "surrealdb": {
      "command": "node",
      "args": ["$(npm which -g surrealdb-mcp-server)"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "my_namespace",
        "SURREALDB_DB": "my_database",
        "SURREALDB_USER": "my_user",
        "SURREALDB_PASS": "my_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Using Environment Variables

You can also configure the server using environment variables:

SURREALDB_URL=ws://localhost:8000
SURREALDB_NS=my_namespace
SURREALDB_DB=my_database
SURREALDB_USER=my_user
SURREALDB_PASS=my_password

🛠️ Integration with CLI Tools

To use the MCP Server in a custom CLI tool, refer to the following configuration:

{
  "mcpServers": {
    "surrealdb": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\surrealdb-mcp-server.cmd"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000",
        "SURREALDB_NS": "my_namespace",
        "SURREALDB_DB": "my_database",
        "SURREALDB_USER": "my_user",
        "SURREALDB_PASS": "my_password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

⚠️ Important Note

On Windows systems, replace YOUR_USERNAME with your actual username.

💻 Usage Scenarios

Scenario 1: Running as an Independent Server

surrealdb-mcp-server --port 8001 --namespace my_ns --database my_db --user my_user --password my_pass

Scenario 2: Integrating into a Node.js Application

Use the MCP client in your application:

const { Client } = require('surrealdb-mcp-client');
const client = new Client({
  url: 'ws://localhost:8000',
  ns: 'my_namespace',
  db: 'my_database',
  user: 'my_user',
  pass: 'my_password'
});

client.query('SELECT * FROM my_table').then(console.log);

🚧 Troubleshooting

Common Issues

"Module not found" 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 Error

If you get an error "Unable to connect to SurrealDB", check:

1. Ensure that the SurrealDB server is running
2. Verify that the URL, namespace, database, user, and password are correctly configured

🚀 Advanced Topics

Scenario 3: Using in a Production Environment

In a production environment, it's recommended to use Docker for containerized deployment:

FROM node:16

WORKDIR /app

COPY package*.json ./

RUN npm install -g surrealdb-mcp-server

CMD ["surrealdb-mcp-server", "--port", "8001", "--namespace", "prod_ns", "--database", "prod_db", "--user", "prod_user", "--password", "prod_pass"]

Scenario 4: Scaling and Load Balancing

To improve availability, you can use a reverse proxy (such as Nginx) to load balance the MCP Server:

upstream surrealdb_mcp {
    server localhost:8001;
    server localhost:8002;
}

server {
    listen 80;

    location / {
        proxy_pass http://surrealdb_mcp;
    }
}

💡 Best Practices

Performance Optimization

1. Use WebSocket for real-time communication
2. Avoid using too many JOIN operations in queries
3. Regularly perform database maintenance and optimization

Security Recommendations

1. Use a strong password policy
2. Enable SSL certificates for encrypted communication
3. Limit the number of client connections

📚 Appendix

Command-Line Options

Here are the common command-line options for surrealdb-mcp-server:

--port <number>      Specify the port the server listens on, default is 8000.
--namespace <string>  Specify the default namespace.
--database <string>   Specify the default database.
--user <string>       Specify the default username.
--password <string>   Specify the default password.

Environment Variable Reference

Here are the supported key environment variables:

SURREALDB_URL        Server connection address, default is ws://localhost:8000.
SURREALDB_NS         Default namespace.
SURREALDB_DB         Default database.
SURREALDB_USER       Default username.
SURREALDB_PASS       Default password.

🤝 Contribution Guidelines

Contributions are welcome! Please refer to our GitHub repository for code submissions and issue reporting.