MCP Toolbox for Databases — Instalar & Demo ao vivo

Por que usar

Principais recursos

Um binário, múltiplos engines: Postgres, MySQL, BigQuery, Spanner, AlloyDB, Cloud SQL, SQLite, MSSQL, Redis, Couchbase, Dgraph, Neo4j
tools.yaml declarativo — cada ferramenta é uma instrução parametrizada e nomeada, não um canal de SQL livre
Configs prontas (--prebuilt postgres) para uso imediato sem configuração
Connection pooling e autenticação (IAM, OAuth, API key) gerenciados centralmente, não no prompt
Transporte stdio ou HTTP/SSE — funciona com Claude Desktop, Cursor, Codex, IDEs e agentes personalizados
Regras de autorização por ferramenta — restrinja quem pode chamar instruções destrutivas

Demo ao vivo

Como fica na prática

mcp-toolbox-databases.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-toolbox-databases",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-toolbox-databases": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "TOOLS_FILE=/config/tools.yaml",
          "-v",
          "${HOME}/.mcp-toolbox:/config",
          "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
          "--prebuilt",
          "postgres",
          "--stdio"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add mcp-toolbox-databases -- docker run -i --rm -e TOOLS_FILE=/config/tools.yaml -v ${HOME}/.mcp-toolbox:/config us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt postgres --stdio

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: MCP Toolbox for Databases

Como dar ao Claude acesso seguro somente-leitura a um Postgres de produção

👤 Engenheiros de backend/dados que querem analytics via LLM sem risco de exfiltração ⏱ ~25 min intermediate

Quando usar: Você quer que o Claude responda perguntas sobre um banco de dados real sem uma ferramenta genérica execute_sql que possa fazer DROP TABLE.

Pré-requisitos

Postgres acessível via URL libpq — Use uma role somente-leitura; nunca o usuário com permissão de escrita da aplicação
Docker ou Go instalado — O Toolbox vem como binário único; imagem Docker é a forma mais fácil

Fluxo

Execute o Toolbox com o perfil postgres pré-configurado

Inicie o mcp-toolbox em modo stdio usando --prebuilt postgres com POSTGRES_URL apontando para a réplica de leitura.✓ Copiado

→ O Toolbox registra tools registered: list_tables, describe_table, execute_sql_readonly
Configure no Claude Desktop

Adicione a configuração docker do toolbox ao claude_desktop_config.json em mcpServers, depois reinicie o Claude.✓ Copiado

→ /mcp lista as ferramentas do toolbox — sem falhas
Faça uma pergunta real

Toolbox: liste as tabelas. Depois, para orders, qual é o valor mediano do pedido nos últimos 7 dias? Mostre o SQL exato que foi executado.✓ Copiado

→ O Claude chama list_tables → describe_table → execute_sql_readonly com um SELECT (nunca UPDATE/DELETE)

Resultado: Analytics somente-leitura sobre dados reais com risco zero de mutação e log de auditoria de cada consulta.

Armadilhas

Apontado para o usuário com permissão de escrita — o Claude eventualmente chama uma ferramenta mutante — Sempre use uma role com apenas GRANT SELECT; verifique com \du no psql
Connection pool esgotado em chamadas paralelas do agente — Defina pool.max_open_conns no tools.yaml; o padrão é conservador

Combine com: filesystem · github

Defina uma ferramenta analítica personalizada com validação de parâmetros

👤 Times que não querem SQL livre, apenas consultas aprovadas ⏱ ~20 min intermediate

Quando usar: Você quer que o Claude responda 'top 10 clientes deste mês' mas nunca invente seus próprios joins.

Pré-requisitos

Arquivo tools.yaml — Crie em ~/.mcp-toolbox/tools.yaml

Fluxo

Escreva uma ferramenta parametrizada

Adicione uma ferramenta top_customers ao tools.yaml: parâmetro since: date, instrução SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ Copiado

→ O Toolbox recarrega e expõe apenas top_customers — sem execute_sql_readonly
Chame via Claude

Use top_customers since=2026-04-01 e explique o resultado.✓ Copiado

→ Chamada única com parâmetro de data validado e resultado formatado

Resultado: Superfície analítica bloqueada — o Claude não pode executar nada que você não tenha declarado.

Armadilhas

Esquecer de remover a ferramenta execute_sql pré-configurada — Remova --prebuilt; carregue apenas seu tools.yaml

Explore datasets do BigQuery sem escrever SQL

👤 Analistas no Google Cloud ⏱ ~20 min intermediate

Quando usar: Você tem um projeto BigQuery e quer que o Claude responda perguntas com controles de custo.

Pré-requisitos

Projeto GCP + dataset — Execute gcloud auth application-default login para que o Toolbox use as credenciais

Fluxo

Inicie o Toolbox com --prebuilt bigquery

Execute o toolbox --prebuilt bigquery com PROJECT=my-proj.✓ Copiado

→ Ferramentas bq_list_datasets, bq_dry_run, bq_query registradas
Sempre faça dry-run antes

Antes de executar qualquer consulta, chame bq_dry_run para estimar os bytes processados. Se > 1GB, pergunte-me antes de executar.✓ Copiado

→ Estimativa de custo exibida antes da consulta billable

Resultado: Respostas do BigQuery com controles de custo — sem surpresas de $200.

Armadilhas

Mismatch de localização padrão (US vs EU) — Defina a variável de ambiente BIGQUERY_LOCATION

Consulte múltiplos bancos de dados em uma única sessão do Claude

👤 Engenheiros depurando problemas entre datastores ⏱ ~30 min advanced

Quando usar: Dados de pedidos estão no Postgres, eventos no BigQuery, cache no Redis — você precisa correlacionar tudo.

Pré-requisitos

tools.yaml com múltiplas fontes — Defina cada fonte em sources: e associe ferramentas à fonte

Fluxo

Configure as três fontes

Adicione postgres-prod, bq-events e redis-cache como fontes no tools.yaml. Adicione 1–2 ferramentas por fonte.✓ Copiado

→ O Toolbox inicia com todas as fontes marcadas como saudáveis
Faça uma pergunta entre datastores

Para o pedido 12345: busque a linha do Postgres, a timeline de eventos do BigQuery e o estado atual do cache do Redis. Reconcilie.✓ Copiado

→ Três chamadas de ferramenta em paralelo, resposta coerente única

Resultado: Depuração entre datastores sem três ferramentas separadas ou sessões SSH.

Armadilhas

Verificação de saúde da fonte falha silenciosamente — Execute toolbox validate tools.yaml antes de iniciar

Combine com: filesystem

Combinações

Combine com outros MCPs para 10× de alavancagem

mcp-toolbox-databases + filesystem

Busque um resultado de consulta e salve como CSV no workspace

Toolbox: top 100 pedidos desta semana. Filesystem: salve como /tmp/orders.csv.✓ Copiado

mcp-toolbox-databases + github

Abra um PR com uma migration SQL após o Claude propor uma alteração de schema

Toolbox: descreva a tabela orders. GitHub: abra um PR adicionando um índice em customer_id.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_tables	schema?: str	Primeira etapa de exploração	1 query
describe_table	table: str	Antes de escrever SQL contra uma tabela desconhecida	1 query
execute_sql_readonly	sql: str	Analytics livre na réplica de leitura	1 query
bq_dry_run	sql: str	BigQuery: sempre antes do bq_query	free (dry run)
bq_query	sql: str	Após o dry run mostrar custo aceitável	billable per bytes scanned
<your-custom-tool>	depends on tools.yaml	Qualquer coisa que você declarou no tools.yaml	1 query

Custo e limites

O que custa rodar

Cota de API: Nenhuma — limitado pelo limite de conexões do seu banco de dados
Tokens por chamada: 100–5000 dependendo do tamanho do resultado
Monetário: OSS gratuito; banco de dados / cloud cobrado normalmente
Dica: Limite as linhas de resultado no tools.yaml (ex: LIMIT 200); para BigQuery, sempre passe pelo bq_dry_run antes

Segurança

Permissões, segredos, alcance

Escopos mínimos: read-only DB role

Armazenamento de credenciais: Variáveis de ambiente ou Google ADC; o Toolbox nunca persiste credenciais

Saída de dados: Conexão direta ao banco de dados — sem passar por terceiros. O Toolbox é apenas local.

Nunca conceda: DBA DROP/TRUNCATE on prod

Sempre coloque uma réplica de leitura com role somente-leitura na frente do prod; nunca use o usuário com permissão de escrita da aplicação

Solução de problemas

Erros comuns e correções

connection refused / pool exhausted

Aumente pool.max_open_conns no tools.yaml; verifique o limite de conexões do banco

Verificar: psql, execute SELECT count(*) FROM pg_stat_activity

tool not found

Usando --prebuilt, o nome da ferramenta é ex: pg_list_tables; verifique com toolbox list-tools

BigQuery 403 access denied

Execute gcloud auth application-default login e conceda roles/bigquery.dataViewer

Verificar: bq ls

Erros do Spanner Cloud SDK

Defina GOOGLE_APPLICATION_CREDENTIALS para um JSON de service account

Alternativas

MCP Toolbox for Databases vs. outros

Alternativa	Quando usar	Troca
DBHub	Você quer um binário único sem dependências cobrindo Postgres/MySQL/SQL Server	Menor profundidade em BigQuery/Spanner, sem Google IAM
Postgres MCP (modelcontextprotocol)	Apenas Postgres, sem configuração YAML	Menos restritivo — expõe execute_sql por padrão
MySQL MCP (benborla)	Apenas MySQL, somente-leitura	Engine único, mais simples

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills