MCP Postgres

O que faz

O MCP Postgres conecta o Claude Code a um banco de dados PostgreSQL usando o

protocolo MCP (Model Context Protocol). Com ele, o agente passa a "enxergar" o

schema do seu banco — tabelas, colunas, tipos — e consegue responder perguntas em

português transformando-as em SQL, executar consultas e explicar os resultados, tudo

sem que você precise abrir um cliente SQL separado.

O foco do plugin é segurança. O servidor MCP oficial de Postgres opera em modo de

leitura, o que significa que o Claude pode consultar dados, mas não derruba tabelas

nem altera registros por engano. Isso o torna ideal para análise exploratória,

geração de relatórios ad-hoc, depuração de dados e onboarding de novos devs que

precisam entender um banco desconhecido.

Casos de uso típicos:

• "Quantos pedidos foram pagos no mês passado, por canal?"
• "Quais tabelas têm relação com usuarios?"
• "Gere um SQL que liste os 20 clientes que mais compraram."
• "Esse campo status pode ser nulo? Quais valores aparecem na prática?"

Instalação

1. Copie a pasta mcp-postgres/ para o diretório de plugins do Claude Code.
2. Garanta que você tem Node.js 18+ instalado (o servidor MCP é baixado via npx).
3. Defina a variável de ambiente POSTGRES_URL com a string de conexão do seu banco

(veja a seção Configuração).

1. Reinicie o Claude Code. O arquivo .mcp.json registra automaticamente o servidor

postgres, que será iniciado sob demanda.

Comandos disponíveis

• /pg-consultar — transforma uma pergunta em linguagem natural em SQL de leitura,

executa via MCP e explica o resultado.

• /pg-schema — descreve o schema do banco (tabelas, colunas, chaves e relações)

para você entender a estrutura antes de consultar.

Configuração

Referencie tudo por nome de variável de ambiente — nunca cole credenciais reais no

projeto nem no .mcp.json (ele usa ${POSTGRES_URL} justamente para isso).

• POSTGRES_URL — obrigatória. String de conexão no formato

postgresql://USUARIO:SENHA@HOST:PORTA/BANCO. Recomenda-se usar um usuário com

permissão somente de leitura (SELECT).

• PGSSLMODE — opcional; defina como require para conexões TLS obrigatórias.

Boa prática: crie um usuário dedicado para o Claude, por exemplo:

CREATE USER claude_ro WITH PASSWORD '...';
GRANT CONNECT ON DATABASE meu_banco TO claude_ro;
GRANT USAGE ON SCHEMA public TO claude_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_ro;

Assim, mesmo que algo dê errado, o agente não consegue escrever no banco.

Exemplo de uso

/pg-schema

O Claude lista as tabelas e mostra que pedidos se relaciona com clientes por

cliente_id. Em seguida:

/pg-consultar Quanto faturamos por mês nos últimos 6 meses, só pedidos pagos?

Ele gera um SQL com GROUP BY date_trunc('month', ...), executa via MCP e devolve uma

tabela com os valores, além de um comentário curto sobre a tendência.

Segurança e limites

• Use sempre um usuário somente-leitura. O servidor MCP oficial é read-only, mas a

permissão no banco é a sua linha de defesa real.

• Nunca exponha a POSTGRES_URL em commits. Mantenha-a em variáveis de ambiente

ou em um gerenciador de segredos. O .mcp.json referencia a variável, não o valor.

• Dados sensíveis: consultas podem trazer dados pessoais (LGPD). Não copie

resultados sensíveis para fora de ambientes controlados.

• Limites de performance: consultas pesadas rodam no seu banco real. Prefira

apontar para uma réplica de leitura quando for analisar tabelas grandes.

• Sem escrita: este plugin não cria, não altera e não apaga dados por design. Para

migrações e mudanças de schema, use ferramentas próprias com revisão humana.