Conecta PostgreSQL a Claude Code mediante MCP, configura una cuenta de solo lectura con control de permisos y deja que Claude lea esquemas, escriba consultas y analice datos directamente.
Una vez que conectas una base de datos, Claude Code funciona de otra manera. No necesitas copiar la estructura de las tablas al prompt ni explicar cómo se llaman los campos — Claude se conecta directamente, lee el esquema, escribe las consultas y analiza los resultados.
Este artículo usa PostgreSQL como ejemplo y recorre todo el proceso desde la configuración hasta el uso real.
El oficial @modelcontextprotocol/server-postgres soporta:
Solo lectura. Este Server está diseñado únicamente para consultas — no ejecuta INSERT, UPDATE ni DELETE.
npm install -g @modelcontextprotocol/server-postgres
Edita .claude/settings.json (a nivel de proyecto):
{
"mcpServers": {
"db": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://readonly_user:password@localhost:5432/myapp_production"
]
}
}
}
Formato de la cadena de conexión: postgresql://USER:PASSWORD@HOST:PORT/DATABASE
Si no quieres escribir la contraseña en el archivo de configuración, usa una variable de entorno:
{
"mcpServers": {
"db": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://readonly_user:password@localhost:5432/myapp_production"
}
}
}
}
Si .claude/settings.json se va a subir a git, asegúrate de que no contiene contraseñas en texto plano. Pon la configuración sensible en .claude/settings.local.json y añádelo al .gitignore.
No le des a Claude una cuenta con permisos de escritura. Crea un usuario de solo lectura en PostgreSQL:
-- Crear el usuario de solo lectura
CREATE USER claude_readonly WITH PASSWORD 'your_password';
-- Conceder acceso de conexión
GRANT CONNECT ON DATABASE myapp_production TO claude_readonly;
-- Conceder uso del schema
GRANT USAGE ON SCHEMA public TO claude_readonly;
-- Conceder SELECT en todas las tablas existentes
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
-- Aplicar lo mismo a tablas futuras
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO claude_readonly;
Si hay tablas que no quieres que Claude vea (como sessions o audit_logs), simplemente no les des permisos, o muévelas a un schema separado.
Reinicia Claude Code y pregunta:
Lista todas las tablas de la base de datos
Si Claude devuelve una lista de nombres de tablas en lugar de decir "no tengo acceso a una base de datos", la conexión MCP funciona.
Una vez configurado, Claude puede hacer bastante más. Algunos escenarios prácticos:
Escenario 1: Entender la estructura de datos
¿Qué relación existe entre las tablas users y orders?
¿Hay restricciones de clave foránea?
Claude consulta directamente information_schema para leer la estructura de tablas y restricciones, y te da una explicación clara — sin que tengas que pegar el esquema.
Escenario 2: Análisis de datos
De los usuarios que se registraron en los últimos 30 días,
¿qué porcentaje ha hecho al menos un pedido?
Desglosado por canal de registro.
Claude escribe el SQL, lo ejecuta y analiza los resultados. Si la consulta falla (nombre de campo incorrecto, por ejemplo), ve el error y se corrige solo.
Escenario 3: Depuración
Encuentra pedidos con status = 'pending' que tengan más de 7 días de antigüedad.
¿Cuántos hay y cuándo fue creado el más reciente?
Este tipo de consultas ad hoc antes requería escribir SQL tú mismo o abrir una herramienta de base de datos. Ahora basta con describir lo que necesitas.
Escenario 4: Apoyo al desarrollo
Quiero añadir una columna last_login_at a la tabla users.
Escribe el SQL de la migración y comprueba si los índices actuales son suficientes.
Claude revisa la estructura actual de la tabla, escribe la migración y analiza el estado de los índices, todo de una vez.
Por defecto, Claude puede acceder al esquema completo y los datos de todas las tablas para las que le hayas dado permisos. Ajusta esto según tus necesidades.
Control por tabla
Concede permisos solo a tablas específicas:
-- Solo tablas concretas, no todas
GRANT SELECT ON TABLE users, orders, products TO claude_readonly;
-- sessions, payment_tokens, audit_logs no reciben acceso
Filtrar columnas sensibles con una vista
Si una tabla tiene campos sensibles (hashes de contraseña, API keys, números de teléfono), crea una vista que los oculte:
CREATE VIEW users_safe AS
SELECT id, email, created_at, plan, status
FROM users;
-- excluye password_digest, phone, payment_method_id
GRANT SELECT ON users_safe TO claude_readonly;
-- no concedas acceso a la tabla original
Claude solo puede consultar la vista y nunca ve los campos originales.
Límite de filas
@modelcontextprotocol/server-postgres aplica por defecto un límite de filas en los resultados (normalmente 1.000 filas), evitando que Claude traiga tablas enteras. Este límite es razonable — no lo aumentes.
Las bases de datos de producción normalmente no exponen su puerto directamente. Usa un túnel SSH:
# Redirige localhost:5433 al puerto 5432 del servidor remoto
ssh -L 5433:localhost:5432 [email protected] -N
Luego usa el puerto local en tu configuración:
"postgresql://readonly_user:password@localhost:5433/myapp_production"
También puedes usar un connection pooler como pgBouncer.
Si tu proyecto usa varias bases de datos (principal, analytics, caché), configura varios 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..."]
}
}
}
Claude se conecta a las dos. Solo dile a cuál debe consultar.
El cambio más notable después de conectar una base de datos es que las conversaciones sobre datos ya no requieren preparación. No hace falta explicar el esquema ni describir los tipos de campo — dices lo que necesitas y Claude lo busca.
Es especialmente útil al depurar. El flujo anterior: consultas la DB → copias los resultados → se los pegas a Claude → los analiza. El nuevo flujo: describes el problema → Claude consulta directamente → obtienes conclusiones.