Por que você ia querer isso

Imagine perguntar ao Claude: “Você me escreve uma consulta que encontre os clientes que não pedem nada há seis meses?”. Em vez de descrever o seu esquema e torcer, o Claude pode percorrer as suas tabelas reais, entender o seu modelo de dados e gerar SQL correto em segundos.

Ou você está depurando um comportamento em produção. Em vez de puxar dados na mão e colar em um chat, o Claude consulta o seu banco de dados direto, vê padrões e faz perguntas sobre o que encontra.

O Model Context Protocol (MCP) torna isso seguro e prático. Ele dá ao Claude um jeito estruturado de consultar o seu banco de dados sem expô-lo a risco ilimitado.

A base da segurança: acesso somente leitura

Antes de entrar na configuração, a regra de ouro: o Claude só deve ler dados, nunca alterá-los. Não é desconfiança — é limite. Se algo der errado (uma consulta mal formulada, uma interpretação inesperada, um bug na conexão), o pior que acontece é uma consulta lenta ou um resultado confuso, não perda de dados.

Para garantir isso, o PostgreSQL permite criar papéis apenas com permissão SELECT. Esses papéis não conseguem fazer INSERT, UPDATE nem DELETE. Nem criar tabelas temporárias. É o princípio do menor privilégio aplicado com rigor.

Em bancos de produção, use uma réplica de leitura — uma cópia sincronizada do seu banco que atende só consultas de leitura. Não é apenas uma camada de segurança. É prático também: consultas de IA podem ser caras e lentas, e você não quer essa carga batendo no seu banco principal.

O que é MCP e por que ele importa?

O MCP é um protocolo aberto que permite a modelos de IA se conectarem a ferramentas e bancos de dados externos de forma segura e estruturada. Em vez de o Claude abrir conexões SQL cruas, ele usa o MCP como intermediário.

Here's the flow:

  • Você roda um servidor MCP (neste caso, o servidor PostgreSQL da Anthropic) na sua máquina ou na sua infraestrutura.
  • O Claude Code (ou o Claude Desktop) se conecta a esse servidor como cliente MCP.
  • Quando o Claude precisa de dados, ele manda requisições estruturadas pelo MCP, não comandos SQL crus.
  • O servidor MCP cuida de inspecionar o esquema, validar a consulta e executá-la.
  • O Claude vê os resultados e consegue raciocinar sobre os seus dados.

Essa estrutura cria uma fronteira de segurança. O Claude não escreve as próprias strings de conexão nem gerencia credenciais diretamente. O servidor MCP é dono da conexão, valida as requisições e aplica as permissões.

Configuração passo a passo de PostgreSQL + Claude Code

1. Pré-requisitos

You'll need:

  • Node.js 18 ou posterior (confira com node --version)
  • Um banco de dados PostgreSQL ao qual você consiga se conectar (local ou remoto)
  • Claude Code ou Claude Desktop (é preciso assinatura Pro para MCP)
  • Uma string de conexão do PostgreSQL pronta (mais abaixo, se precisar criar uma)

2. Crie um papel somente leitura no PostgreSQL

Conecte-se ao seu banco PostgreSQL como administrador. Se estiver usando um banco local:

psql -U postgres -h localhost

Depois rode estes comandos para criar um papel somente leitura:

-- Create the read-only role CREATE ROLE claude_readonly WITH LOGIN PASSWORD 'strong_password_here'; -- Grant connection to the database GRANT CONNECT ON DATABASE your_database TO claude_readonly; -- Grant usage on schemas (assuming public schema) GRANT USAGE ON SCHEMA public TO claude_readonly; -- Grant SELECT on all tables GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly; -- Ensure future tables are also readable ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO claude_readonly;

Troque your_database pelo nome real do seu banco e escolha uma senha forte. Esse papel já lê todas as tabelas, mas não consegue escrever, apagar nem alterar nada.

3. Monte a sua string de conexão

As strings de conexão do PostgreSQL seguem este formato:

postgresql://username:password@host:port/database

For example:

postgresql://claude_readonly:strong_password_here@localhost:5432/your_database

Se o seu banco é remoto (por exemplo, no Render ou no Railway), use a string de conexão que eles fornecem. Se SSL for exigido, acrescente ?sslmode=require no fim.

4. Configure o Claude Code ou o Claude Desktop

Você tem duas opções: pela linha de comando ou configuração manual.

Opção A: usar o comando claude mcp add

Se você usa o Claude Code, rode:

claude mcp add postgres postgresql://claude_readonly:password@localhost:5432/your_database

Troque a string de conexão pela sua. Esse comando atualiza o seu arquivo de configuração automaticamente.

Opção B: configuração manual (Claude Desktop ou instalação detalhada)

Edite ou crie o ~/.claude.json (na sua pasta pessoal) e adicione este bloco:

{ "mcpServers": { "postgres": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-postgres", "postgresql://claude_readonly:password@localhost:5432/your_database" ] } } }

Salve o arquivo. Reinicie o Claude Code ou o Claude Desktop. A conexão deve iniciar na próxima abertura.

5. Teste a conexão

Abra o Claude Code. Em uma conversa nova, peça ao Claude que mostre as tabelas do seu banco:

What tables do I have in this database? Can you describe the schema?

Se a conexão funcionar, o Claude vai listar as suas tabelas e descrever colunas, restrições e relações. Se falhar, verifique:

  • Se o PostgreSQL está rodando e acessível a partir da sua máquina
  • Se a string de conexão está correta (principalmente a senha)
  • Se o papel somente leitura tem as permissões certas (rode de novo os comandos GRANT acima, na dúvida)
  • Se for remoto, confirme que o seu firewall e a configuração de rede permitem a conexão

O atalho do Supabase

Se você quer algo mais rápido, o Supabase (um backend gerenciado de PostgreSQL) oferece uma integração MCP pronta. Cadastre-se em supabase.com, crie um projeto (que sobe um banco PostgreSQL na hora) e conecte-o ao Claude com o servidor MCP oficial deles.

A vantagem: sem criar papéis na mão nem se preocupar com infraestrutura. O custo: o servidor MCP do Supabase é só para desenvolvimento e testes, não para produção. Para um experimento rápido ou para aprender, ainda assim é difícil de superar.

Importante: O servidor MCP do Supabase nunca deve ser conectado a dados de produção. Ele foi feito para explorar e desenvolver. Para bancos de produção, siga a configuração manual do PostgreSQL acima.

Exemplos práticos: o que pedir ao Claude

Uma vez conectado, você pode pedir ao Claude que:

  • Explore os seus dados: “Quantos usuários há no banco? Qual é o intervalo de datas dos pedidos?”
  • Gere consultas: “Escreva uma consulta que encontre os usuários que estão há 90 dias sem entrar.”
  • Detecte padrões: “Existem tabelas com um número de linhas incomumente alto? O que isso pode significar?”
  • Depure: “Por que esta coluna pode ter valores nulos para alguns usuários?”
  • Sugira otimizações: “Quais consultas provavelmente ficarão lentas com este esquema?”

O Claude vai ver os formatos reais dos dados, as restrições e as relações, o que torna as respostas dele muito mais úteis do que se você tivesse apenas descrito o banco por escrito.

O que pode dar errado (e como evitar)

Consultas lentas ou descontroladas

Se o Claude escrever uma consulta que varre milhões de linhas, o seu banco vai sentir. Mitigação: rode o Claude contra uma réplica de leitura, não contra o banco principal. Configure statement_timeout no PostgreSQL para cortar consultas que durem mais de (digamos) 30 segundos.

ALTER ROLE claude_readonly SET statement_timeout = '30s';

Expor dados sensíveis

Se o seu banco contém dados pessoais, senhas, chaves de API ou segredos, o Claude vai vê-los se estiverem em colunas legíveis. Antes de conectar uma IA ao seu banco, audite o que há lá dentro. Mascare ou exclua as colunas sensíveis, ou tire tabelas inteiras do papel somente leitura:

-- Exclude the secrets table REVOKE SELECT ON secrets FROM claude_readonly;

Credenciais de conexão no chat

Nunca cole no Claude uma string de conexão com senha real. A configuração fica no ~/.claude.json, na sua máquina, e não nas suas conversas. Se alguma vez você colar uma senha em algum lugar, troque-a imediatamente.

Exposição de rede

Se o seu PostgreSQL está em um servidor remoto, garanta que ele só aceite conexões do seu endereço IP ou por uma VPN. Não abra a porta 5432 para a internet toda. Configure o pg_hba.conf com rigor.

Perguntas frequentes

Preciso do Claude Pro para usar isso?

Sim. O suporte a MCP exige Claude Desktop (Pro) ou Claude Code. No plano gratuito não dá para usar MCP.

O Claude consegue escrever no meu banco de dados?

Não, se você configurou o papel somente leitura corretamente. As permissões do papel no PostgreSQL vão bloquear qualquer tentativa de INSERT, UPDATE ou DELETE. O Claude recebe um erro se tentar.

É seguro conectar o meu banco de produção?

Só se você conectar uma réplica de leitura, e não o principal. Uma réplica de leitura é uma cópia sincronizada que atende apenas leituras. Assim, mesmo que algo dê errado, o seu banco principal fica intacto. Em sistemas críticos, teste antes contra uma cópia de homologação.

Posso conectar vários bancos de dados?

Sim. Adicione várias entradas ao objeto mcpServers no ~/.claude.json, cada uma com nome e string de conexão diferentes. O Claude terá acesso a todos eles em uma mesma sessão.

E se o meu banco estiver atrás de um firewall ou de uma VPN?

O cliente do Claude Code (que roda na sua máquina) cuida da conexão, então se você alcança o banco a partir da sua máquina, o Claude também alcança. Não é preciso nenhuma configuração de rede além da que você já tem.

Como o Claude sabe quais tabelas e colunas eu tenho?

O servidor MCP do PostgreSQL inspeciona o seu esquema na conexão. Ele puxa a lista de tabelas, os nomes das colunas, os tipos, as restrições e as relações direto das tabelas de sistema do PostgreSQL. O Claude vê essa informação e a usa para escrever consultas mais inteligentes.

Próximos passos

Comece pequeno. Conecte primeiro um banco de desenvolvimento ou de homologação. Faça ao Claude perguntas exploratórias simples: “Mostre o esquema”. “Quantas linhas há em cada tabela?”. Quando estiver confortável, passe a escrever consultas e resolver problemas.

Para bancos maiores ou casos de uso mais avançados, veja o servidor MCP do pgEdge ou outras alternativas. Para prototipar rápido, vale testar a opção gerenciada do Supabase. O princípio não muda: acesso somente leitura, MCP como intermediário e limites claros sobre o que a IA pode fazer.