Conecte o PostgreSQL ao Claude Code via MCP, configure uma conta somente leitura com controle de permissões e deixe o Claude ler schemas, escrever queries e analisar dados diretamente.
Depois de conectar um banco de dados, o Claude Code funciona de forma diferente. Você não precisa copiar a estrutura das tabelas para o prompt nem explicar como os campos se chamam — o Claude se conecta diretamente, lê o schema, escreve as consultas e analisa os resultados.
Este artigo usa PostgreSQL como exemplo e percorre todo o processo do início ao fim.
O oficial @modelcontextprotocol/server-postgres suporta:
Somente leitura. Este Server é projetado apenas para consultas — não executa INSERT, UPDATE ou DELETE.
npm install -g @modelcontextprotocol/server-postgres
Edite .claude/settings.json (nível de projeto):
{
"mcpServers": {
"db": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://readonly_user:password@localhost:5432/myapp_production"
]
}
}
}
Formato da string de conexão: postgresql://USER:PASSWORD@HOST:PORT/DATABASE
Se não quiser colocar a senha no arquivo de configuração, use variável de ambiente:
{
"mcpServers": {
"db": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://readonly_user:password@localhost:5432/myapp_production"
}
}
}
}
Se .claude/settings.json for commitado no git, certifique-se de que não há senha em texto puro. Coloque configurações sensíveis no .claude/settings.local.json e adicione-o ao .gitignore.
Não dê ao Claude uma conta com permissões de escrita. Crie um usuário somente leitura no PostgreSQL:
-- Criar o usuário somente leitura
CREATE USER claude_readonly WITH PASSWORD 'your_password';
-- Conceder acesso de conexão
GRANT CONNECT ON DATABASE myapp_production TO claude_readonly;
-- Conceder uso do schema
GRANT USAGE ON SCHEMA public TO claude_readonly;
-- Conceder SELECT em todas as tabelas existentes
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
-- Aplicar o mesmo a tabelas futuras
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO claude_readonly;
Se houver tabelas que você não quer que o Claude veja (como sessions ou audit_logs), simplesmente não conceda permissão a elas, ou mova-as para um schema separado.
Reinicie o Claude Code e pergunte:
Liste todas as tabelas do banco de dados
Se o Claude retornar uma lista de tabelas em vez de dizer "não tenho acesso ao banco de dados", a conexão MCP está funcionando.
Com a configuração pronta, o Claude consegue fazer muito mais. Alguns cenários práticos:
Cenário 1: Entender a estrutura dos dados
Qual é a relação entre as tabelas users e orders?
Existem restrições de chave estrangeira?
O Claude consulta o information_schema diretamente para ler a estrutura e restrições das tabelas e te dá uma explicação clara — sem precisar colar o schema.
Cenário 2: Análise de dados
Dos usuários que se cadastraram nos últimos 30 dias,
qual percentual fez pelo menos um pedido?
Divida por canal de cadastro.
O Claude escreve o SQL, executa e analisa os resultados. Se a consulta falhar (nome de campo errado, por exemplo), ele vê o erro e se corrige sozinho.
Cenário 3: Debugging
Encontre pedidos com status = 'pending' criados há mais de 7 dias.
Quantos são e quando foi criado o mais recente?
Esse tipo de consulta ad hoc antes exigia escrever SQL manualmente ou abrir uma ferramenta de banco de dados. Agora basta descrever o que você precisa.
Cenário 4: Suporte ao desenvolvimento
Quero adicionar uma coluna last_login_at na tabela users.
Escreva o SQL da migração e verifique se os índices existentes são suficientes.
O Claude lê a estrutura atual da tabela, escreve a migração e analisa os índices — tudo de uma vez.
Por padrão, o Claude tem acesso ao schema completo e aos dados de todas as tabelas para as quais você concedeu permissão. Restrinja conforme necessário.
Controle por tabela
Conceda acesso apenas a tabelas específicas:
-- Somente tabelas específicas, não todas
GRANT SELECT ON TABLE users, orders, products TO claude_readonly;
-- sessions, payment_tokens, audit_logs não recebem acesso
Filtrar colunas sensíveis com uma view
Se uma tabela tiver campos sensíveis (hash de senha, API keys, números de telefone), crie uma view que os oculte:
CREATE VIEW users_safe AS
SELECT id, email, created_at, plan, status
FROM users;
-- exclui password_digest, phone, payment_method_id
GRANT SELECT ON users_safe TO claude_readonly;
-- não conceda acesso à tabela original
O Claude só consegue consultar a view e nunca vê os campos originais.
Limite de linhas
O @modelcontextprotocol/server-postgres aplica por padrão um limite de linhas nos resultados (geralmente 1.000 linhas), impedindo que o Claude traga tabelas inteiras. Esse limite é razoável — não aumente.
Bancos de dados de produção normalmente não expõem sua porta diretamente. Use um túnel SSH:
# Redireciona localhost:5433 para a porta 5432 do servidor remoto
ssh -L 5433:localhost:5432 [email protected] -N
Use a porta local na configuração:
"postgresql://readonly_user:password@localhost:5433/myapp_production"
Outra opção é usar um connection pooler como pgBouncer.
Se o projeto usa vários bancos de dados (principal, analytics, cache), configure múltiplos MCP Servers:
{
"mcpServers": {
"main-db": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://...principal..."]
},
"analytics-db": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://...analytics..."]
}
}
}
O Claude se conecta aos dois. Basta dizer qual usar em cada situação.
A mudança mais perceptível depois de conectar um banco de dados é que conversas sobre dados não precisam mais de preparação. Sem explicar schema, sem descrever tipos de campo — você fala o que precisa e o Claude busca sozinho.
É especialmente útil no debugging. O fluxo antigo: você consulta o banco → copia os resultados → cola para o Claude → ele analisa. O novo fluxo: você descreve o problema → o Claude consulta diretamente → você recebe as conclusões.