Servidor MCP DBeaver | Awesome MCP Servers

OmniSQL MCP

Servidor MCP universal de banco de dados — dê aos assistentes de IA acesso de leitura/escrita aos seus bancos de dados usando conexões já salvas no workspace do seu cliente de banco de dados local (compatível com DBeaver).

Suporte a Bancos de Dados

Suporte nativo (driver direto, rápido):

PostgreSQL (via pg)
MySQL / MariaDB (via mysql2)
SQL Server / MSSQL (via mssql)
SQLite (via CLI sqlite3)

Compatível com Postgres (roteado automaticamente pelo driver pg):

CockroachDB, TimescaleDB, Amazon Redshift, YugabyteDB, AlloyDB, Supabase, Neon, Citus

Outros bancos de dados: Recorre a uma CLI externa configurada via OMNISQL_CLI_PATH. Os resultados variam conforme a CLI.

Drivers personalizados que encapsulam qualquer um dos acima são detectados automaticamente — consulte Drivers Personalizados e com Autenticação IAM.

Recursos

Reutiliza conexões já configuradas no workspace do seu cliente de banco de dados local — sem configuração duplicada
Execução nativa de consultas para PostgreSQL, MySQL/MariaDB, SQLite, SQL Server
Autenticação IAM do AWS RDS, incluindo drivers personalizados baseados no AWS Advanced JDBC Wrapper
Pool de conexões com tamanho e timeouts configuráveis
Suporte a transações (BEGIN/COMMIT/ROLLBACK)
Análise de plano de execução de consultas (EXPLAIN)
Comparação de esquemas entre conexões com geração de scripts de migração
Modo somente leitura com SELECT obrigatório em execute_query
Lista de permissões de conexões para restringir quais bancos de dados são acessíveis
Filtragem de ferramentas para desabilitar operações específicas
Validação de consultas para bloquear operações perigosas (DROP DATABASE, TRUNCATE, DELETE/UPDATE sem WHERE)
Exportação de dados para CSV/JSON
Desligamento gracioso com limpeza do pool de conexões

Requisitos

Node.js 18+
Um cliente de banco de dados local (compatível com DBeaver) com pelo menos uma conexão configurada

Instalação

npm install -g omnisql-mcp

Configuração

Claude Desktop

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Claude Code

Adicione ao ~/.claude/settings.json:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Cursor

Adicione em Configurações do Cursor > Servidores MCP:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp"
    }
  }
}

Variáveis de Ambiente

Variável	Descrição	Padrão
`OMNISQL_CLI_PATH`	Caminho para a CLI do cliente de banco de dados externo (usado para fallback de driver não suportado)	Não definido
`OMNISQL_WORKSPACE`	Caminho para o diretório do workspace do cliente de banco de dados local	Padrão do SO
`OMNISQL_PROJECT`	Nome da pasta do projeto/workspace do cliente de banco de dados (ex.: projeto DBeaver com nome personalizado)	`General`
`OMNISQL_TIMEOUT`	Timeout de consulta (ms)	`30000`
`OMNISQL_DEBUG`	Ativar log de depuração	`false`
`OMNISQL_READ_ONLY`	Desabilitar todas as operações de escrita	`false`
`OMNISQL_ALLOWED_CONNECTIONS`	Lista separada por vírgulas de IDs ou nomes de conexões na lista de permissões	Todas
`OMNISQL_DISABLED_TOOLS`	Ferramentas separadas por vírgulas para desabilitar	Nenhuma
`OMNISQL_POOL_MIN`	Conexões mínimas por pool	`2`
`OMNISQL_POOL_MAX`	Conexões máximas por pool	`10`
`OMNISQL_POOL_IDLE_TIMEOUT`	Timeout de conexão ociosa (ms)	`30000`
`OMNISQL_POOL_ACQUIRE_TIMEOUT`	Timeout de aquisição de conexão (ms)	`10000`
`OMNISQL_AWS_CLI_PATH`	Caminho para a CLI do AWS (usado para autenticação IAM do RDS)	`aws`
`OMNISQL_IAM_TOKEN_TIMEOUT`	Timeout para gerar um token de autenticação IAM do RDS (ms)	`20000`
`OMNISQL_SSH_KNOWN_HOSTS`	Arquivo known_hosts usado para verificar hosts de túnel SSH	`~/.ssh/known_hosts`
`OMNISQL_SSH_STRICT_HOST_KEY`	Recusar hosts de túnel SSH sem entrada `known_hosts`	`false`

Modo Somente Leitura

Bloqueia todas as operações de escrita. A ferramenta execute_query permite apenas declarações SELECT, EXPLAIN, SHOW e DESCRIBE. As ferramentas de transação são desabilitadas completamente.

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_READ_ONLY": "true"
      }
    }
  }
}

Lista de Permissões de Conexões

Restringe quais conexões do workspace são visíveis. Aceita IDs de conexão ou nomes de exibição, separados por vírgulas:

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_ALLOWED_CONNECTIONS": "dev-postgres,staging-mysql"
      }
    }
  }
}

Desabilitar Ferramentas Específicas

{
  "mcpServers": {
    "omnisql": {
      "command": "omnisql-mcp",
      "env": {
        "OMNISQL_DISABLED_TOOLS": "drop_table,alter_table,write_query"
      }
    }
  }
}

Ferramentas Disponíveis

Gerenciamento de Conexões

list_connections - Listar todas as conexões de banco de dados
get_connection_info - Obter detalhes da conexão
test_connection - Testar conectividade

Operações de Dados

execute_query - Executar consultas somente leitura (apenas SELECT, EXPLAIN, SHOW, DESCRIBE)
write_query - Executar INSERT/UPDATE/DELETE
export_data - Exportar para CSV/JSON

Gerenciamento de Esquemas

list_tables - Listar tabelas e visões
get_table_schema - Obter estrutura da tabela
create_table - Criar tabelas
alter_table - Modificar tabelas
drop_table - Excluir tabelas (requer confirmação)

Transações

begin_transaction - Iniciar uma nova transação
execute_in_transaction - Executar consulta dentro de uma transação
commit_transaction - Confirmar uma transação
rollback_transaction - Reverter uma transação

Análise de Consultas

explain_query - Analisar plano de execução de consulta
compare_schemas - Comparar esquemas entre duas conexões
get_pool_stats - Obter estatísticas do pool de conexões

Outros

get_database_stats - Estatísticas do banco de dados
append_insight - Armazenar notas de análise
list_insights - Recuperar notas armazenadas

Segurança

Imposição de somente leitura: execute_query aceita apenas declarações somente leitura (SELECT, EXPLAIN, SHOW, DESCRIBE, PRAGMA). Operações de escrita devem usar write_query.
Validação de consultas: Bloqueia DROP DATABASE, DROP SCHEMA, TRUNCATE, DELETE/UPDATE sem WHERE, GRANT, REVOKE e declarações de gerenciamento de usuários.
Lista de permissões de conexões: Restringe quais conexões são expostas via OMNISQL_ALLOWED_CONNECTIONS.
Filtragem de ferramentas: Desabilite qualquer ferramenta via OMNISQL_DISABLED_TOOLS.
Sanitização de entrada: IDs de conexão e identificadores SQL são sanitizados para prevenir injeção.
Recomendação: Para uso em produção, use também um usuário somente leitura no nível do banco de dados para defesa em profundidade.

Suporte a Formatos de Workspace

Suporta ambos os formatos de configuração escritos por clientes de banco de dados compatíveis com DBeaver:

Legado: Configuração XML em .metadata/.plugins/org.jkiss.dbeaver.core/
Moderno: Configuração JSON em General/.dbeaver/

O nome da pasta do projeto/workspace (General por padrão) é configurável via OMNISQL_PROJECT, para que workspaces que usam um projeto DBeaver personalizado ou renomeado (ex.: DataPlatform) sejam descobertos sem precisar renomear o projeto ou criar link simbólico para a pasta.

Modos de conexão

As conexões DBeaver são configuradas manualmente (campos de host, porta, banco de dados) ou por URL (uma URL JDBC). Ambos funcionam. No modo URL, o DBeaver deixa os campos de host/porta em valores de espaço reservado — geralmente localhost — e lê apenas a URL, então a URL é o que é usado aqui também.

Túneis SSH

Conexões que o DBeaver alcança por meio de um túnel SSH são tuneladas aqui também. O túnel é aberto no primeiro uso e reutilizado durante toda a vida do servidor, com um encaminhamento local somente loopback, e o host/porta da conexão são tratados como o DBeaver os trata: como o banco de dados como visto a partir do servidor SSH.

Autenticação por agente, senha e chave pública são suportadas, obtidas da aba SSH da conexão. Credenciais salvas no workspace (incluindo as do próprio túnel, armazenadas separadamente das credenciais do banco de dados) são descriptografadas e usadas.
A autenticação por agente precisa de SSH_AUTH_SOCK definido no ambiente do servidor MCP. Clientes MCP geralmente não herdam seu shell, então defina-o explicitamente na configuração do servidor do cliente se você usar um agente.
A chave de host SSH é verificada contra known_hosts. Um host registrado lá deve corresponder, ou o túnel é recusado; um host que não está registrado é aceito, a menos que OMNISQL_SSH_STRICT_HOST_KEY=true.
Se um túnel não puder ser aberto, a conexão falha com esse motivo. Nunca recorre a conectar diretamente ao host registrado, o que alcançaria um banco de dados local não relacionado.

Consultando outro banco de dados no mesmo servidor

Um ID de conexão pode carregar uma substituição de banco de dados — my-connection/analytics — para executar contra um banco de dados diferente no mesmo servidor sem adicionar uma segunda conexão no DBeaver. Isso não se aplica a mecanismos baseados em arquivos, como SQLite, onde o "banco de dados" é um caminho de arquivo.

Com OMNISQL_ALLOWED_CONNECTIONS definido, colocar uma conexão na lista de permissões permite os bancos de dados que suas credenciais podem alcançar. Para fixá-la em bancos de dados específicos, liste entradas connection/database em vez da conexão simples.

As credenciais são descriptografadas automaticamente do workspace credentials-config.json.

Drivers Personalizados e com Autenticação IAM

Drivers personalizados

O roteamento nativo normalmente depende do ID do driver (postgres-jdbc, mysql8). Drivers personalizados frequentemente usam um ID opaco — um UUID, por exemplo — que não nomeia nenhum mecanismo. Essas conexões são resolvidas recorrendo ao provider da conexão (postgresql, mysql, …) e depois ao sub-protocolo da URL JDBC, incluindo os encapsulados, como jdbc:aws-wrapper:postgresql://…. Um driver personalizado que encapsula um mecanismo suportado, portanto, funciona sem configuração extra.

Se um mecanismo ainda não puder ser identificado, o erro resultante nomeia tanto o ID do driver quanto o provedor para que você possa ver o que estava faltando.

Autenticação IAM do AWS RDS

Conexões que autenticam com um token IAM do RDS em vez de uma senha armazenada são detectadas e tratadas automaticamente. Ambas as formas são reconhecidas:

Drivers AWS Advanced JDBC Wrapper, que registram wrapperPlugins: "iam" junto com awsProfile e iamRegion.
Os modelos de autenticação IAM da AWS do próprio cliente de banco de dados.

Para essas conexões, o OmniSQL:

Gera um token com aws rds generate-db-auth-token (via CLI da AWS, então perfis SSO e com cadeia de papéis funcionam conforme configurado) e o usa como senha.
Armazena em cache cada token por 13 minutos, dentro de sua vida útil de 15 minutos, e regenera por conexão física para que pools de longa duração continuem funcionando.
Força TLS, que o RDS exige para tokens IAM.
Resolve o nome de usuário do banco de dados a partir da conexão quando presente. Quando ausente, o nome de usuário é derivado da sua identidade AWS: ou o nome do papel por desenvolvedor (<profile>-<user>) ou o nome da sessão SSO assumida.

Requisitos: a CLI da AWS em PATH (ou OMNISQL_AWS_CLI_PATH), uma sessão válida para o perfil da conexão (aws sso login --profile <profile>) e acessibilidade de rede ao endpoint. Uma sessão SSO expirada produz um erro nomeando o perfil para reautenticar.

Desenvolvimento

git clone https://github.com/srthkdev/omnisql-mcp.git
cd omnisql-mcp
npm install
npm run build
npm test
npm run lint

Licença

MIT

DBeaver MCP Server

Documentação