DB-MCP

DB MCP Gateway

Dê ao Claude Code, Cursor, Windsurf ou qualquer ferramenta de IA compatível com MCP acesso somente leitura aos seus bancos de dados — sem expor credenciais ou arriscar alterações de dados.

Auto-hospedado. Tudo roda localmente. Suas senhas nunca saem da sua máquina.

https://github.com/user-attachments/assets/f768ff6f-3c9e-4583-9179-c7022d3b7487

Bancos de dados suportados

	Banco de dados	Observações
	PostgreSQL	Todas as versões
	MySQL	MySQL 5.7+ / MariaDB
	SQLite	Arquivo local, sem necessidade de servidor
	Amazon Redshift	SSL obrigatório, consultas de catálogo específicas do Redshift

---

O que ele faz

Em vez de copiar e colar resultados de consultas entre seu cliente de banco de dados e sua ferramenta de IA, o gateway permite que sua IA consulte o banco de dados diretamente. Ela pode explorar esquemas, inspecionar tabelas e executar consultas SELECT. Ela não pode inserir, atualizar, excluir ou remover nada.

---

Início rápido

Opção A — Docker (recomendado, sem necessidade de instalação local)

git clone https://github.com/mdadul/db-mcp
cd db-mcp

# Generate .env with secure random keys, then start
sh scripts/setup.sh
docker compose up

docker compose baixa a imagem pré-construída do Docker Hub — nenhuma etapa de build necessária.
O MCP_TOKEN é exibido por setup.sh — copie-o antes de fechar o terminal.

---

Opção B — Nativo (requer Bun)

git clone https://github.com/mdadul/db-mcp
cd db-mcp
bun install
bun run dev   # generates .env automatically, then starts the server

Abra http://localhost:4080.
Seu MCP_TOKEN está em .env.

---

Conecte sua ferramenta de IA

Claude Code (CLI)

claude mcp add --transport http db-mcp http://localhost:4080/mcp \
  --header "Authorization: Bearer <MCP_TOKEN>"

Em seguida, reinicie o Claude Code.

Cursor / Windsurf / Claude Desktop

Adicione ao seu mcp.json:

{
  "mcpServers": {
    "db-mcp": {
      "url": "http://localhost:4080/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_TOKEN>"
      }
    }
  }
}

Claude.ai Web

O Claude.ai exige HTTPS. Exponha o gateway por meio de um túnel primeiro:

# Option A — Cloudflare (no account needed)
npx cloudflared tunnel --url http://localhost:4080

# Option B — ngrok
ngrok http 4080

Copie a URL https://... da saída do túnel e adicione-a em Claude.ai → Configurações → Integrações → Adicionar servidor MCP.

---

Usando com sua IA

Depois de conectado, basta perguntar naturalmente:

"Quantos pedidos foram criados esta semana?" "Quais colunas a tabela users tem?" "Mostre-me os últimos 10 jobs com falha."

A IA chamará as ferramentas do gateway automaticamente — sem copiar e colar.

Ferramentas disponíveis

Ferramenta	O que ela faz
list_databases	Lista todos os bancos de dados conectados
get_database_schema	Lista tabelas (filtro de nome opcional)
get_table_schema	Mostra colunas, índices e chaves estrangeiras de uma tabela
execute_read_query	Executa uma consulta SELECT (limitada a 100 linhas por padrão, máximo 1000)

---

Variáveis de ambiente

Variável	Obrigatória	Descrição
DATABASE_PATH	Sim	Caminho para o armazenamento local de metadados SQLite (ex.: ./data/db-mcp.sqlite)
ENCRYPTION_KEY	Sim	Chave hex de 64 caracteres para criptografia de credenciais. Gere: openssl rand -hex 32
MCP_TOKEN	Sim	Token Bearer para o endpoint /mcp. Gere: openssl rand -base64 32
PORT	Não	Porta HTTP (padrão: 4080)

Um arquivo .env é criado com valores gerados na primeira execução.

---

Solução de problemas

Ferramentas não aparecendo no Claude Code Reinicie o Claude Code após adicionar o servidor MCP. Se ainda estiverem ausentes, execute claude mcp list para confirmar que está registrado e mostra ✓ Connected.

"Falha ao conectar" no Claude Code Verifique se o gateway está em execução (http://localhost:4080 deve carregar) e se o token na sua configuração corresponde a .env.

Erros de "sessão não encontrada" O gateway não tem estado — cada solicitação é independente. Se você vir isso, reconecte o servidor MCP no seu IDE.

"A URL deve começar com https" (Claude.ai Web) O Claude.ai bloqueia HTTP simples. Use um túnel — veja a configuração do Claude.ai Web acima.

Conexão recusada ao meu banco de dados Se o gateway roda em Docker e seu banco de dados está no host, use host.docker.internal em vez de localhost como host.

---

Notas de segurança

• O MCP_TOKEN controla o acesso a todos os seus bancos de dados por meio do gateway. Trate-o como uma senha.
• As credenciais do banco de dados são criptografadas com AES-256-GCM. A chave existe apenas em ENCRYPTION_KEY — nunca no banco de dados.
• Apenas SELECT, SHOW, DESCRIBE e EXPLAIN são permitidos. Operações de escrita são rejeitadas na camada do gateway antes de chegarem ao banco de dados.
• Todas as consultas são registradas no painel web na aba Logs de cada banco de dados.