Postgres MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Somente leitura por design — INSERT/UPDATE/DELETE/DDL são bloqueados no nível do protocolo
Introspecção completa de esquema: tabelas, colunas, tipos, índices, chaves estrangeiras
Retorna planos de consulta (EXPLAIN) para análise de desempenho
String de conexão postgres:// padrão — funciona com qualquer BD compatível com PG (Postgres, Neon, Supabase, RDS, Aiven, etc.)

Demo ao vivo

Como fica na prática

postgres.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

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

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

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

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

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "postgres",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  ]
}

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

~/.config/zed/settings.json

{
  "context_servers": {
    "postgres": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://..."
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://...

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

Casos de uso

Usos do mundo real: Postgres

Responda a perguntas comerciais ad-hoc sem tocar em SQL

👤 PMs, fundadores, qualquer pessoa que preferiria não escrever SQL ⏱ ~10 min beginner

Quando usar: Você tem uma pergunta sobre seus dados ('quantos usuários voltaram esta semana?') e o dashboard de BI não tem.

Pré-requisitos

String de conexão postgres:// somente leitura para uma réplica — A maioria dos PG gerenciados (RDS, Neon, Supabase) permite criar credenciais somente leitura
Acesso de rede de onde o Claude é executado para o BD — VPN ou lista de permissões de IP para sua máquina

Fluxo

Peça ao Claude para fazer introspecção das tabelas relevantes primeiro

Liste todas as tabelas em nosso BD. Para tabelas relacionadas a usuários, pedidos ou sessões, descreva seus esquemas.✓ Copiado

→ Visão geral do esquema antes de qualquer consulta
Faça a pergunta real

Quantos usuários se inscreveram nos últimos 30 dias mas ainda não fizeram um pedido? Agrupe por semana de inscrição.✓ Copiado

→ Claude escreve SQL, executa, retorna tabela de resultados
Investigue ressalvas

Há razões pelas quais esse número poderia ser enganoso? Exclusões reversíveis? Fuso horário em created_at? Tipos de usuário específicos que devemos excluir?✓ Copiado

→ Chamada honesta de peculiaridades de dados

Resultado: Uma resposta defensável para uma pergunta comercial com o SQL, o resultado e as ressalvas — em 2 minutos em vez de esperar 2 dias pela equipe de dados.

Armadilhas

Claude escreve uma consulta que verifica sua tabela maior sem limites — Defina statement_timeout = '30s' na conexão e adicione 'sempre inclua LIMIT 1000 por padrão' ao seu prompt de sistema
Contar 'usuários' depende do que conta como um usuário (deletado? bot? teste?) — Diga ao Claude suas convenções antecipadamente: 'exclua linhas onde deleted_at IS NOT NULL' etc.

Combine com: notion

Diagnostique por que uma consulta é lenta e sugira índices

👤 Engenheiros backend, DBAs ⏱ ~15 min intermediate

Quando usar: Você tem uma consulta que é mais lenta do que deveria ser. Você quer um segundo par de olhos que não se cansa lendo a saída EXPLAIN ANALYZE.

Fluxo

Obtenha o plano de consulta

Execute EXPLAIN ANALYZE nesta consulta: [colar]. Caminhe-me pelo que o planejador está fazendo.✓ Copiado

→ Análise passo a passo do plano
Identifique o fator de custo

Qual etapa é responsável pela maioria do custo? É uma varredura sequencial, uma ordem de junção ruim ou filtragem cara?✓ Copiado

→ Nó específico identificado com motivo
Sugira um índice ou reescreva

Sugira a menor alteração para tornar isso rápido. Prefira adicionar um índice a reescrever a consulta, mas apenas se o índice fosse útil para >1 consulta.✓ Copiado

→ Instrução CREATE INDEX concreta OU consulta reescrita

Resultado: Uma consulta indexada ou reescrita, com justificativa, que você pode verificar executando EXPLAIN novamente.

Armadilhas

EXPLAIN em um conjunto de dados não representativo (BD de dev pequeno) fornece planos enganosos — Sempre execute EXPLAIN em um banco de dados com dados em forma de produção; caso contrário, o plano é ficção
Adicionar um índice parece gratuito mas reduz a velocidade das escritas — Diga ao Claude para verificar se o índice seria usado verificando com EXPLAIN ANTES de pedir para adicioná-lo

Combine com: sentry

Audite uma tabela para problemas de qualidade de dados

👤 Engenheiros de dados, qualquer pessoa herdando um esquema desconhecido ⏱ ~25 min intermediate

Quando usar: Você está prestes a construir um recurso em cima de uma tabela que não foi projetada e suspeita que tem problemas.

Fluxo

Execute uma bateria de verificações NULL / duplicado / órfão

Para a tabela orders: conte valores NULL por coluna, conte linhas duplicadas por alguma chave natural (por exemplo (user_id, stripe_payment_intent_id)), conte linhas com chaves estrangeiras apontando para linhas pai deletadas.✓ Copiado

→ Contagem de problemas por verificação
Verifique se há peculiaridades na distribuição de valores

Quais são a distribuição mín, máx e percentil para total_cents? Existem suspeitosamente muitas linhas com valores 0 ou negativos?✓ Copiado

→ Estatísticas de distribuição, outliers sinalizados
Verificação cruzada contra regras comerciais esperadas

Todo pedido 'concluído' deve ter um paid_at não nulo. Existem exceções?✓ Copiado

→ Contagem de violações + IDs de amostra

Resultado: Uma lista curta de bugs concretos de integridade de dados, cada um com uma contagem e um caminho de correção.

Armadilhas

Alguns 'problemas' são artefatos históricos intencionais (migrações de dados) — Sempre confirme com alguém que conhece o histórico antes de assumir que é um bug

Gere automaticamente documentação de esquema para sua equipe

👤 Líderes técnicos integrando novos engenheiros ⏱ ~20 min beginner

Quando usar: Seu BD tem 40 tabelas, o wiki tem 0. Novos contratados continuam perguntando 'qual é esta coluna?'

Fluxo

Obtenha todas as tabelas e seus esquemas

Liste todas as tabelas no esquema público. Para cada, forneça colunas, tipos, nulabilidade, padrões e quaisquer chaves estrangeiras.✓ Copiado

→ Despejo completo do esquema
Deduza o propósito do nomeação + dados de amostra

Para cada tabela, amostre 3 linhas e escreva uma descrição de um parágrafo do que esta tabela representa em nossos negócios.✓ Copiado

→ Explicação em prosa por tabela
Sinalize tabelas desconhecidas / suspeitas

Existem tabelas que parecem não utilizadas ou cuja finalidade você não consegue inferir? Liste-as para que eu possa perguntar ao autor original.✓ Copiado

→ Lista honesta 'Não sei o que são'

Resultado: Um documento Markdown que sua equipe pode adicionar a Notion ou um wiki — cobrindo 80% do que os novos contratados precisam saber.

Armadilhas

Amostragem de dados sensíveis (PII) no contexto do LLM — Para tabelas com PII, peça ao Claude para descrever esquemas apenas sem amostrar linhas

Combine com: notion · filesystem

Calcule resultados de teste A/B de dados de evento bruto

👤 Analistas de produto, engenheiros de crescimento ⏱ ~30 min advanced

Quando usar: Você executou um experimento, os dados estão em seu BD e deseja números de significância sem escrever SQL manualmente.

Pré-requisitos

Tabela de eventos com atribuição de experimento + eventos de conversão — Esquema padrão: events(user_id, experiment, variant, timestamp), conversions(user_id, type, timestamp)

Fluxo

Calcule a taxa de conversão por variante

Para experimento 'checkout-redesign-2026': quantos usuários foram atribuídos a cada variante e qual foi a taxa de conversão (pelo seu evento de conversão) por variante?✓ Copiado

→ Tabela por variante com taxas
Calcule significância estatística

Calcule o valor p de chi-quadrado para a diferença entre controle e tratamento. O resultado é estatisticamente significativo em p < 0,05?✓ Copiado

→ valor p com veredicto
Verificação de sanidade dos números

Os tamanhos de amostra estão equilibrados? O experimento foi executado por tempo suficiente? Algum segmento onde o resultado se inverte?✓ Copiado

→ Verificação de saúde, não apenas valor p

Resultado: Um relatório de teste A/B estatisticamente defensável com o SQL, os números e as ressalvas.

Armadilhas

Olhar para resultados antes do tamanho de amostra pré-definido leva a falsos positivos — Faça o Claude verificar se o teste atingiu seu tamanho de amostra alvo antes de calcular significância

Combine com: notion

Combinações

Combine com outros MCPs para 10× de alavancagem

postgres + notion

Execute uma consulta, publique resultados como uma tabela Notion para partes interessadas que não têm acesso BD

Consulte nossos 10 principais clientes por receita vitalícia este trimestre, depois crie uma página Notion em 'Sales Reports' com os resultados como uma tabela formatada.✓ Copiado

postgres + sentry

Referência cruzada do estado BD com erros — quando um erro menciona um ID de registro, procure-o

Problema Sentry WEB-3a91 menciona order_id 99214. Procure esse pedido e diga-me se algo nos dados da linha poderia explicar o crash.✓ Copiado

postgres + filesystem

Exporte resultados de consulta como CSV/JSON para uso a jusante

Execute minha consulta de churn-cohort e salve o resultado como /reports/churn-2026-04.csv.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_tables	schema?: str	Primeira etapa em qualquer sessão — descubra o esquema	free
describe_table	table: str, schema?: str	Obtenha a estrutura completa de uma tabela específica antes de consultar	free
query	sql: str	Execute qualquer SQL somente leitura — apenas SELECT	depends on query

Custo e limites

O que custa rodar

Cota de API: Limitado pelo limite de conexão e tempo limite de consulta do seu BD
Tokens por chamada: Consultas de esquema: ~500 tokens. Conjuntos de resultados: depende da contagem de linhas — limite com LIMIT
Monetário: Gratuito — custos são o que sua fatura de hospedagem BD já é
Dica: Sempre defina um statement_timeout na conexão (por exemplo ?options=-c%20statement_timeout%3D30000) para que uma consulta descontrolada não possa derrubar seu BD.

Segurança

Permissões, segredos, alcance

Escopos mínimos: SELECT nas tabelas que você deseja expor

Armazenamento de credenciais: String de conexão em var env. Use um papel somente leitura dedicado: CREATE ROLE claude_readonly LOGIN PASSWORD '...'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

Saída de dados: Todas as consultas para seu BD; linhas de resultado enviadas para qualquer provedor de LLM que você use

Nunca conceda: INSERT UPDATE DELETE DROP TRUNCATE ALTER

Mesmo consultas somente leitura podem ser caras — envolva com SET statement_timeout se conectar à produção.
Use uma string de conexão de réplica de leitura em produção.

Solução de problemas

Erros comuns e correções

FATAL: password authentication failed

Verifique a string de conexão. Causa comum: caracteres especiais em senha não codificados em URL.

Verificar: psql 'postgres://...' -c 'SELECT 1'

no pg_hba.conf entry / SSL required

Anexe ?sslmode=require à string de conexão. A maioria do Postgres gerenciado requer SSL.

permission denied for table X

A função não tem SELECT nessa tabela. Execute GRANT SELECT ON X TO claude_readonly.

Verificar: psql -c '\dp X'

canceling statement due to statement timeout

A consulta era muito lenta. Otimize-a (adicione um índice, estreite a cláusula WHERE) ou aumente o tempo limite para essa conexão.

Alternativas

Postgres vs. outros

Alternativa	Quando usar	Troca
Supabase MCP	Você está no Supabase — obtenha gerenciamento completo de projeto mais SQL	Inclui acesso de escrita; menos seguro para produção
Neon MCP	Você está no Neon — adiciona ramificação para teste de migração seguro	Recursos específicos de Neon funcionam apenas em BDs Neon
dbHub	Você precisa de suporte a vários bancos de dados (Postgres, MySQL, MongoDB, etc.) em um MCP	Mais novo; suporta mais BDs mas cada integração é mais superficial
sqlite MCP	BD baseado em arquivo local em vez de servidor	Sem acesso concorrente, sem rede, mas configuração zero

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills