Servidor MCP SurrealDB | Awesome MCP Servers

SurrealDB MCP Server

SurrealDB MCP Server Logo

Um servidor Model Context Protocol (MCP) que fornece uma interface padronizada para assistentes de IA interagirem com um banco de dados SurrealDB. Este servidor permite que sistemas de IA consultem e manipulem dados dentro de uma instância SurrealDB configurada.

Nota para Assistentes de IA: Se você é um assistente de IA (como Claude, Cline, Copilot, etc.) lendo esta documentação, consulte o arquivo llms-install.md para instruções detalhadas especificamente projetadas para você ajudar usuários a instalar e configurar este servidor MCP.

Guia de Instalação

Qual assistente de IA você está usando?

📝 Usando a extensão Cline no VS Code? → Ir para Instalação do Cline
🖥️ Usando o aplicativo Claude Desktop? → Ir para Instalação do Claude
🤖 Usando GitHub Copilot no VS Code? → Ir para Instalação do Copilot
🦘 Usando Roo Code no VS Code? → Ir para Instalação do Roo Code
🌊 Usando Windsurf? → Ir para Instalação do Windsurf
⚡ Usando Cursor? → Ir para Instalação do Cursor
🔄 Usando n8n? → Ir para Integração com n8n

Termos-chave

Servidor MCP: Um servidor que implementa o Model Context Protocol, permitindo que assistentes de IA acessem ferramentas e recursos externos
Host MCP: O aplicativo (como VS Code com Cline ou Claude Desktop) que se conecta a servidores MCP
SurrealDB: Um banco de dados document-graph escalável, distribuído e com capacidades em tempo real

Ferramentas Disponíveis

O servidor expõe as seguintes ferramentas para interagir com o SurrealDB:

query: Executar uma consulta SurrealQL bruta.
select: Selecionar registros de uma tabela (todos ou por ID específico).
create: Criar um único novo registro em uma tabela.
update: Atualizar um registro específico, substituindo seu conteúdo.
delete: Excluir um registro específico por ID.
merge: Mesclar dados em um registro específico (atualização parcial).
patch: Aplicar operações JSON Patch a um registro específico.
upsert: Criar um registro se ele não existir, ou atualizá-lo se existir.
insert: Inserir vários registros em uma tabela.
insertRelation: Criar uma relação de grafo (aresta) entre dois registros.

(Consulte a listagem de ferramentas do host MCP para esquemas de entrada detalhados.)

📝 Instalação do Cline

Instalação com um clique para a extensão Cline no VS Code

Instale o pacote globalmente:
```
npm install -g surrealdb-mcp-server
```

Adicione às configurações do Cline:

Edite o arquivo em: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Adicione a seguinte configuração:

{
  "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: Substitua YOUR_USERNAME pelo seu nome de usuário real do Windows no caminho.

Reinicie o VS Code
Verifique a instalação:
- Abra o Cline no VS Code
- Peça ao Cline para "listar servidores MCP disponíveis"
- Você deve ver "surrealdb" na lista

🖥️ Instalação do Claude

Instalação para o aplicativo Claude Desktop

Configure o Claude Desktop para usar o servidor:

Edite o arquivo de configurações MCP do aplicativo Claude Desktop:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Adicione a seguinte configuração:
```
{
  "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 o comando npx como mostrado acima significa que o cliente MCP baixará e executará automaticamente o pacote do npm quando necessário. Nenhuma instalação manual é necessária.
Reinicie o aplicativo Claude Desktop
Verifique a instalação:
- Peça ao Claude para "listar servidores MCP disponíveis"
- Você deve ver "surrealdb" na lista

🤖 Instalação do Copilot

Instalação para GitHub Copilot no VS Code

Crie um arquivo de configuração do workspace:

Crie um arquivo em: .vscode/mcp.json no seu workspace

Adicione a seguinte configuração:

{
  "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 configuração usa as variáveis de entrada do VS Code para solicitar e armazenar com segurança suas credenciais do SurrealDB.

Verifique a instalação:
- Abra o GitHub Copilot Chat no VS Code
- Selecione o modo "Agent" no menu suspenso
- Clique no botão "Tools" para ver as ferramentas disponíveis
- Você deve ver as ferramentas do SurrealDB na lista

🦘 Instalação do Roo Code

Instalação para Roo Code no VS Code

Acesse as configurações MCP:

Clique no ícone MCP na navegação superior do painel do Roo Code e selecione "Edit MCP Settings" para abrir o arquivo de configuração.

Adicione a configuração do SurrealDB MCP Server:

{
  "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: Substitua YOUR_USERNAME pelo seu nome de usuário real do Windows no caminho.

Reinicie o VS Code
Verifique a instalação:
- Abra o Roo Code no VS Code
- Clique no ícone MCP para ver os servidores disponíveis
- Você deve ver "surrealdb" na lista

🌊 Instalação do Windsurf

Instalação para Windsurf

Instale o pacote globalmente:
```
npm install -g surrealdb-mcp-server
```
Configure o Windsurf:
- Abra o Windsurf no seu sistema
- Navegue até a página de Configurações
- Vá para a aba Cascade
- Encontre a seção de Servidores Model Context Protocol (MCP)
- Clique em "View raw config" para abrir o arquivo de configuração (normalmente em ~/.codeium/windsurf/mcp_config.json)

Adicione a configuração do SurrealDB MCP Server:

{
  "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: Substitua /path/to/global/node_modules pelo caminho real do seu diretório node_modules global.

Reinicie o Windsurf
Verifique a instalação:
- Abra o Cascade no Windsurf
- Você deve ver as ferramentas do SurrealDB disponíveis na lista de ferramentas

⚡ Instalação do Cursor

Instalação para Cursor

Instale o pacote globalmente:
```
npm install -g surrealdb-mcp-server
```
Configure o Cursor:
- Abra o Cursor
- Vá para Configurações > Configurações do Cursor
- Encontre a opção MCP Servers e ative-a
- Clique em "Add New MCP Server"

Adicione a configuração do SurrealDB MCP Server:

{
  "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: Substitua /path/to/global/node_modules pelo caminho real do seu diretório node_modules global.

Reinicie o Cursor
Verifique a instalação:
- Abra o Cursor Chat
- Você deve ver as ferramentas do SurrealDB disponíveis na lista de ferramentas

Variáveis de Ambiente Necessárias

Este servidor requer as seguintes variáveis de ambiente para se conectar à sua instância SurrealDB:

SURREALDB_URL: O endpoint WebSocket da sua instância SurrealDB (por exemplo, ws://localhost:8000 ou wss://cloud.surrealdb.com).
SURREALDB_NS: O Namespace de destino.
SURREALDB_DB: O Database de destino.
SURREALDB_USER: O nome de usuário para autenticação (usuário Root, NS, DB ou Scope).
SURREALDB_PASS: A senha do usuário especificado.

Solução de Problemas

Problemas Comuns

Erro "Cannot find module"

Se você vir um erro como "Cannot find module 'surrealdb-mcp-server'", tente:

Verifique a instalação global: npm list -g surrealdb-mcp-server
Verifique se o caminho na sua configuração corresponde ao caminho real da instalação
Tente reinstalar: npm install -g surrealdb-mcp-server

Erros de Conexão

Se você vir "Failed to connect to SurrealDB":

Verifique se o SurrealDB está em execução: surreal start --log debug
Verifique sua URL de conexão, namespace, database e credenciais
Certifique-se de que sua instância SurrealDB esteja acessível a partir do caminho especificado

Problemas Específicos do Cline

Se a abordagem npx não funcionar com o Cline:

Sempre use o método de instalação global para o Cline
Especifique o caminho completo para node.exe e o pacote instalado
Certifique-se de substituir YOUR_USERNAME pelo seu nome de usuário real do Windows

Configuração Avançada

Usando uma Build Local

Se você clonou o repositório ou deseja usar uma build local, você pode usar esta configuração:

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

Substitua /path/to/your/surrealdb-mcp-server pelo caminho real onde você clonou o repositório
Substitua os valores das variáveis de ambiente pelos seus detalhes reais de conexão do SurrealDB

Desenvolvimento

Se você deseja contribuir para o desenvolvimento deste servidor MCP, siga estes passos:

Configuração de Desenvolvimento Local

Clone o repositório:

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

Instale as dependências:
```
npm install
```
Compile o projeto:
```
npm run build
```

Executando Localmente

# 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

Testes

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

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes.

Integração com n8n

Você pode integrar este SurrealDB MCP Server com n8n usando o nó da comunidade n8n-nodes-mcp.

NOTA: Atualmente, apenas a versão self-hosted (Docker) do n8n suporta nós da comunidade. Não há opção para MCP Servers na versão cloud do n8n (ainda?).

Instalação

Instale o pacote n8n-nodes-mcp:
```
npm install n8n-nodes-mcp
```
Configure o n8n para usar o nó personalizado:

Adicione o seguinte à sua configuração do n8n:
```
N8N_CUSTOM_EXTENSIONS="n8n-nodes-mcp"
```
Configure o nó MCP no n8n:
- Adicione o nó "MCP" ao seu fluxo de trabalho
- Configure-o para conectar ao seu SurrealDB MCP Server
- Selecione a operação desejada (query, select, create, etc.)
- Configure os parâmetros da operação

Para mais detalhes, visite o repositório GitHub do n8n-nodes-mcp.

Licença

MIT

SurrealDB MCP Server

Documentação

SurrealDB MCP Server

Guia de Instalação

Qual assistente de IA você está usando?

Termos-chave

Ferramentas Disponíveis

📝 Instalação do Cline

Instalação com um clique para a extensão Cline no VS Code

🖥️ Instalação do Claude

Instalação para o aplicativo Claude Desktop

🤖 Instalação do Copilot

Instalação para GitHub Copilot no VS Code

🦘 Instalação do Roo Code

Instalação para Roo Code no VS Code

🌊 Instalação do Windsurf

Instalação para Windsurf

⚡ Instalação do Cursor

Instalação para Cursor

Variáveis de Ambiente Necessárias

Solução de Problemas

Problemas Comuns

Erro "Cannot find module"

Erros de Conexão

Problemas Específicos do Cline

Configuração Avançada

Usando uma Build Local

Desenvolvimento

Configuração de Desenvolvimento Local

Executando Localmente

Testes

Contribuindo

Integração com n8n

Instalação

Licença