SurrealDB MCP Server

Servidor MCP de SurrealDB

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 de SurrealDB . Este servidor permite a los sistemas de IA consultar y manipular datos dentro de una instancia configurada de SurrealDB.

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

Guía de instalación

¿Qué asistente de IA estás utilizando?

• ¿Usas la extensión Cline de VS Code? → Ir a la instalación de Cline
• ¿Usas la app de escritorio de Claude? → Ir a la instalación de Claude
• ¿Usas GitHub Copilot en VS Code? → Ir a la instalación de Copilot
• ¿Usas Roo Code en VS Code? → Ir a la instalación de Roo Code
• ¿Usas Windsurf? → Ir a Instalación de Windsurf
• ⚡ ¿Usas Cursor? → Ir a Instalación de Cursor
• ¿Usas n8n ? → Ir a la integración de n8n

Términos clave

• Servidor MCP : un servidor que implementa el Protocolo de Contexto de Modelo, lo que permite 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 gráficos de documentos, escalable y distribuida, con capacidades en tiempo real

Herramientas disponibles

El servidor expone las siguientes herramientas para interactuar con SurrealDB:

• query : ejecuta una consulta SurrealQL sin procesar.
• select : selecciona registros de una tabla (todos o por ID específico).
• create : crea un único registro nuevo en una tabla.
• update : Actualiza un registro específico, reemplazando su contenido.
• delete : elimina un registro específico por ID.
• merge : fusionar datos en un registro específico (actualización parcial).
• patch : aplicar operaciones de parche JSON a un registro específico.
• upsert : crea un registro si no existe o lo actualiza si existe.
• insert : inserta varios registros en una tabla.
• insertRelation : Crea una relación gráfica (borde) entre dos registros.

(Consulte la lista de herramientas del host MCP para obtener esquemas de entrada detallados).

📝 Instalación de Cline

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

1. Instalar el paquete globalmente:
   npm install -g surrealdb-mcp-server
2. Agregar a la configuración de Cline:Edite el archivo en: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.jsonAgregue 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.

3. Reiniciar VS Code
4. Verificar la instalación:
   • Abrir Cline en VS Code
   • Pídele a Cline que "enumere los servidores MCP disponibles"
   • Deberías ver "surrealdb" en la lista

🖥️ Instalación de Claude

Instalación de la aplicación de escritorio Claude

1. Configurar Claude Desktop para utilizar el servidor:Edite el archivo de configuración MCP de la aplicación de escritorio Claude:
   • Ventanas: %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.

2. Reiniciar la aplicación de escritorio Claude
3. Verificar la instalación:
   • Pídele a Claude que "enumere los servidores MCP disponibles"
   • Deberías ver "surrealdb" en la lista

🤖 Instalación del copiloto

Instalación de GitHub Copilot en VS Code

1. Crear un archivo de configuración del espacio de trabajo:Crea un archivo en: .vscode/mcp.json en tu espacio de trabajoAgregue 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.

2. Verificar la instalación:
   • Abrir 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ías ver las herramientas de SurrealDB en la lista

🦘 Instalación del código Roo

Instalación de Roo Code en VS Code

1. Acceder a la configuración de MCP:Haga clic en el ícono MCP en la navegación superior del panel Código Roo, luego seleccione "Editar configuración de MCP" para abrir el archivo de configuración.
2. 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.

3. Reiniciar VS Code
4. Verificar la instalación:
   • Abrir Roo Code en VS Code
   • Haga clic en el icono de MCP para ver los servidores disponibles
   • Deberías ver "surrealdb" en la lista

🌊 Instalación de Windsurf

Instalación para Windsurf

1. Instalar el paquete globalmente:
   npm install -g surrealdb-mcp-server
2. Configurar Windsurf:
   • Abra Windsurf en su sistema
   • Vaya a la página de Configuración
   • Vaya a la pestaña Cascada
   • Encuentre la sección Servidores del Protocolo de Contexto de Modelo (MCP)
   • Haga clic en "Ver configuración sin procesar" para abrir el archivo de configuración (normalmente en ~/.codeium/windsurf/mcp_config.json )
3. 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 node_modules.

4. Reiniciar Windsurf
5. Verificar la instalación:
   • Cascada abierta en Windsurf
   • Debería ver las herramientas de SurrealDB disponibles en la lista de herramientas

⚡ Instalación del cursor

Instalación para Cursor

1. Instalar el paquete globalmente:
   npm install -g surrealdb-mcp-server
2. Configurar cursor:
   • Cursor abierto
   • Vaya a Configuración > Configuración del cursor
   • Busque la opción Servidores MCP y habilítela
   • Haga clic en "Agregar nuevo servidor MCP"
3. 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 node_modules.

4. Reiniciar cursor
5. Verificar la instalación:
   • Abrir el chat del cursor
   • 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 punto final WebSocket de su instancia de SurrealDB (por ejemplo, ws://localhost:8000 o wss://cloud.surrealdb.com ).
• SURREALDB_NS : El espacio de nombres de destino.
• SURREALDB_DB : La base de datos de destino.
• SURREALDB_USER : El nombre de usuario para la autenticación (usuario raíz, NS, DB o Scope).
• SURREALDB_PASS : La contraseña para el usuario especificado.

Solución de problemas

Problemas comunes

Error "No se puede encontrar el módulo"

Si ve un error como "No se puede encontrar el módulo 'surrealdb-mcp-server'", intente:

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

Errores de conexión

Si ve "Error al conectarse a SurrealDB":

1. Verifique que SurrealDB se esté ejecutando: surreal start --log debug
2. Verifique su URL de conexión, espacio de nombres, base de datos y credenciales
3. Asegúrese de que su instancia de SurrealDB sea accesible desde la ruta especificada

Problemas específicos de Cline

Si el enfoque npx no funciona con Cline:

1. Utilice siempre el método de instalación global para Cline
2. Especifique la ruta completa a node.exe y el paquete instalado
3. 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 utilizar una compilación local, puede usar esta configuración:

• 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 de conexión reales de SurrealDB

Desarrollo

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

Configuración de desarrollo local

1. Clonar el repositorio:
   git clone https://github.com/nsxdavid/surrealdb-mcp-server.git cd surrealdb-mcp-server
2. Instalar dependencias:
   npm install
3. Construir el proyecto:
   npm run build

Ejecutando localmente

Pruebas

Contribuyendo

¡Agradecemos sus contribuciones! Consulte las normas en CONTRIBUTING.md .

Integración con n8n

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

NOTA: Actualmente, solo la versión autoalojada (Docker) de n8n admite nodos comunitarios. No existe la opción de servidores MCP en la versión en la nube de n8n (¿aún?).

Instalación

1. Instale el paquete n8n-nodes-mcp:
   npm install n8n-nodes-mcp
2. Configure n8n para utilizar el nodo personalizado:Agregue lo siguiente a su configuración n8n:
   N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"
3. Configurar 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, crear, etc.)
   • Configurar los parámetros de operación

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

Licencia

Instituto Tecnológico de Massachusetts (MIT)