Servidor MCP de SurrealDB

SurrealDB MCP Server Logo

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona una interfaz estandarizada para que los asistentes de IA interactúen con una base de datos SurrealDB. Este servidor permite a los sistemas de IA consultar y manipular datos dentro de una instancia de SurrealDB configurada.

Nota para Asistentes de IA: Si usted es un asistente de IA (como Claude, Cline, Copilot, etc.) leyendo esta documentación, consulte el archivo llms-install.md para obtener instrucciones detalladas diseñadas específicamente para ayudarle a los usuarios a instalar y configurar este servidor MCP.

Guía de Instalación

¿Qué asistente de IA está utilizando?

📝 ¿Usando la extensión Cline para VS Code? → Ir a la Instalación de Cline
🖥️ ¿Usando la aplicación de escritorio Claude? → Ir a la Instalación de Claude
🤖 ¿Usando GitHub Copilot en VS Code? → Ir a la Instalación de Copilot
🦘 ¿Usando Roo Code en VS Code? → Ir a la Instalación de Roo Code
🌊 ¿Usando Windsurf? → Ir a la Instalación de Windsurf
⚡ ¿Usando Cursor? → Ir a la Instalación de Cursor
🔄 ¿Usando n8n? → Ir a la Integración con n8n

Términos Clave

Servidor MCP: Un servidor que implementa el Protocolo de Contexto de Modelo, permitiendo a los asistentes de IA acceder a herramientas y recursos externos
Host MCP: La aplicación (como VS Code con Cline o Claude Desktop) que se conecta a los servidores MCP
SurrealDB: Una base de datos de documentos-grafo, escalable y distribuida, con capacidades en tiempo real

Herramientas Disponibles

El servidor expone las siguientes herramientas para interactuar con SurrealDB:

query: Ejecutar una consulta SurrealQL sin procesar.
select: Seleccionar registros de una tabla (todos o por ID específico).
create: Crear un único registro nuevo en una tabla.
update: Actualizar un registro específico, reemplazando su contenido.
delete: Eliminar un registro específico por ID.
merge: Fusionar datos en un registro específico (actualización parcial).
patch: Aplicar operaciones JSON Patch a un registro específico.
upsert: Crear un registro si no existe, o actualizarlo si existe.
insert: Insertar múltiples registros en una tabla.
insertRelation: Crear una relación de grafo (borde) entre dos registros.

(Consulte el listado de herramientas del host MCP para obtener esquemas de entrada detallados.)

📝 Instalación de Cline

Instalación con un clic para la extensión Cline de VS Code

Instale el paquete globalmente:
```
npm install -g surrealdb-mcp-server
```

Agregue a la configuración de Cline:

Edite el archivo en: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Agregue la siguiente configuración:

{
  "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": []
    }
  }
}

Importante: Reemplace YOUR_USERNAME con su nombre de usuario real de Windows en la ruta.

Reinicie VS Code
Verifique la instalación:
- Abra Cline en VS Code
- Pídale a Cline que "liste los servidores MCP disponibles"
- Debería ver "surrealdb" en la lista

🖥️ Instalación de Claude

Instalación para la aplicación de escritorio Claude

Configure Claude Desktop para usar el servidor:

Edite el archivo de configuración MCP de la aplicación de escritorio Claude:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Agregue la siguiente configuración:
```
{
  "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": []
    }
  }
}
```
Nota: Usar el comando npx como se muestra arriba significa que el cliente MCP descargará y ejecutará automáticamente el paquete desde npm cuando sea necesario. No se requiere instalación manual.
Reinicie la aplicación de escritorio Claude
Verifique la instalación:
- Pídale a Claude que "liste los servidores MCP disponibles"
- Debería ver "surrealdb" en la lista

🤖 Instalación de Copilot

Instalación para GitHub Copilot en VS Code

Cree un archivo de configuración del espacio de trabajo:

Cree un archivo en: .vscode/mcp.json en su espacio de trabajo

Agregue la siguiente configuración:

{
  "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}"
      }
    }
  }
}

Nota: Esta configuración utiliza las variables de entrada de VS Code para solicitar y almacenar de forma segura sus credenciales de SurrealDB.

Verifique la instalación:
- Abra GitHub Copilot Chat en VS Code
- Seleccione el modo "Agente" en el menú desplegable
- Haga clic en el botón "Herramientas" para ver las herramientas disponibles
- Debería ver las herramientas de SurrealDB en la lista

🦘 Instalación de Roo Code

Instalación para Roo Code en VS Code

Acceda a la configuración de MCP:

Haga clic en el icono de MCP en la navegación superior del panel de Roo Code, luego seleccione "Editar configuración de MCP" para abrir el archivo de configuración.

Agregue la configuración del servidor MCP de SurrealDB:

{
  "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": []
    }
  }
}

Importante: Reemplace YOUR_USERNAME con su nombre de usuario real de Windows en la ruta.

Reinicie VS Code
Verifique la instalación:
- Abra Roo Code en VS Code
- Haga clic en el icono de MCP para ver los servidores disponibles
- Debería ver "surrealdb" en la lista

🌊 Instalación de Windsurf

Instalación para Windsurf

Instale el paquete globalmente:
```
npm install -g surrealdb-mcp-server
```
Configure Windsurf:
- Abra Windsurf en su sistema
- Navegue a la página de Configuración
- Vaya a la pestaña Cascade
- Encuentre la sección de Servidores de Protocolo de Contexto de Modelo (MCP)
- Haga clic en "Ver configuración sin procesar" para abrir el archivo de configuración (típicamente en ~/.codeium/windsurf/mcp_config.json)

Agregue la configuración del servidor MCP de SurrealDB:

{
  "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"
      }
    }
  ]
}

Nota: Reemplace /path/to/global/node_modules con la ruta real a su directorio global de node_modules.

Reinicie Windsurf
Verifique la instalación:
- Abra Cascade en Windsurf
- Debería ver las herramientas de SurrealDB disponibles en la lista de herramientas

⚡ Instalación de Cursor

Instalación para Cursor

Instale el paquete globalmente:
```
npm install -g surrealdb-mcp-server
```
Configure Cursor:
- Abra Cursor
- Vaya a Configuración > Configuración de Cursor
- Encuentre la opción de Servidores MCP y actívela
- Haga clic en "Agregar nuevo servidor MCP"

Agregue la configuración del servidor MCP de SurrealDB:

{
  "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"
  }
}

Nota: Reemplace /path/to/global/node_modules con la ruta real a su directorio global de node_modules.

Reinicie Cursor
Verifique la instalación:
- Abra Cursor Chat
- Debería ver las herramientas de SurrealDB disponibles en la lista de herramientas

Variables de Entorno Requeridas

Este servidor requiere las siguientes variables de entorno para conectarse a su instancia de SurrealDB:

SURREALDB_URL: El endpoint WebSocket de su instancia de SurrealDB (por ejemplo, ws://localhost:8000 o wss://cloud.surrealdb.com).
SURREALDB_NS: El Namespace de destino.
SURREALDB_DB: La Database de destino.
SURREALDB_USER: El nombre de usuario para la autenticación (usuario Root, NS, DB o Scope).
SURREALDB_PASS: La contraseña para el usuario especificado.

Solución de Problemas

Problemas Comunes

Error "Cannot find module"

Si ve un error como "Cannot find module 'surrealdb-mcp-server'", intente:

Verifique la instalación global: npm list -g surrealdb-mcp-server
Compruebe que la ruta en su configuración coincida con la ruta de instalación real
Intente reinstalar: npm install -g surrealdb-mcp-server

Errores de Conexión

Si ve "Failed to connect to SurrealDB":

Verifique que SurrealDB esté ejecutándose: surreal start --log debug
Compruebe su URL de conexión, namespace, database y credenciales
Asegúrese de que su instancia de SurrealDB sea accesible desde la ruta especificada

Problemas Específicos de Cline

Si el enfoque de npx no funciona con Cline:

Use siempre el método de instalación global para Cline
Especifique la ruta completa a node.exe y al paquete instalado
Asegúrese de reemplazar YOUR_USERNAME con su nombre de usuario real de Windows

Configuración Avanzada

Usando una Compilación Local

Si ha clonado el repositorio o desea usar una compilación local, puede usar esta configuración:

{
  "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": []
    }
  }
}

Reemplace /path/to/your/surrealdb-mcp-server con la ruta real donde clonó el repositorio
Reemplace los valores de las variables de entorno con los detalles reales de su conexión a SurrealDB

Desarrollo

Si desea contribuir al desarrollo de este servidor MCP, siga estos pasos:

Configuración de Desarrollo Local

Clone el repositorio:

git clone https://github.com/nsxdavid/surrealdb-mcp-server.git
cd surrealdb-mcp-server

Instale las dependencias:
```
npm install
```
Compile el proyecto:
```
npm run build
```

Ejecución Local

# 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

Pruebas

npm test # (Note: Tests need to be implemented)

Contribuciones

¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md para obtener las pautas.

Integración con n8n

Puede integrar este servidor MCP de SurrealDB con n8n usando el nodo comunitario n8n-nodes-mcp.

NOTA: Actualmente solo la versión autoalojada (Docker) de n8n admite nodos comunitarios. No hay opción para servidores MCP en la versión en la nube de n8n (¿todavía?).

Instalación

Instale el paquete n8n-nodes-mcp:
```
npm install n8n-nodes-mcp
```
Configure n8n para usar el nodo personalizado:

Agregue lo siguiente a su configuración de n8n:
```
N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"
```
Configure el nodo MCP en n8n:
- Agregue el nodo "MCP" a su flujo de trabajo
- Configúrelo para conectarse a su servidor MCP de SurrealDB
- Seleccione la operación deseada (consulta, selección, creación, etc.)
- Configure los parámetros de la operación

Para más detalles, visite el repositorio de GitHub de n8n-nodes-mcp.

Licencia

MIT

SurrealDB MCP Server

Documentación