MCP PostgreSQL

Servidor Model Context Protocol que expone introspección y consulta read-only sobre PostgreSQL. Diseñado para alimentar de contexto a Claude (Claude Code, Claude Desktop) sin riesgo de escritura.

• 13 tools de introspección, consulta, EXPLAIN y estadísticas de almacenamiento
• 2 resources navegables (postgres://schema/{schema}, postgres://table/{schema}/{table})
• 4 prompts listos para usar (audit-table, find-tables, explain-foreign-keys, profile-slow-query)
• Read-only reforzado: SET TRANSACTION READ ONLY, statement timeout, cap de filas, single-statement, validación de keywords
• Schema allow-list vía DB_SCHEMAS
• Empaquetable como MCPB para Claude Desktop (pnpm run mcpb:pack)

---

Tabla de contenidos

• Quickstart
• Configuración
• Integración con Claude Code
• Integración con Claude Desktop (MCPB)
• Tools
• Resources
• Prompts
• Seguridad
• Estructura del proyecto
• Desarrollo
• Troubleshooting

---

Quickstart

Requisitos: Node ≥ 18 y pnpm.

pnpm install
pnpm run build
cp .env.example .env       # edita tus credenciales
npx tsx test-connection.ts # verifica conectividad

Luego registra el servidor en Claude Code:

claude mcp add --transport stdio postgres \
  -- node /ruta/absoluta/al/proyecto/dist/index.js

Configuración

Copia .env.example a .env y edita los valores:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=nombre_base_datos
DB_USER=usuario
DB_PASSWORD=contraseña
DB_SSL=false                       # true para AWS RDS / Supabase / Neon
DB_SSL_REJECT_UNAUTHORIZED=true    # mantener true en producción
DB_SCHEMAS=public                  # esquemas permitidos, separados por coma. Vacío = todos los no-sistema
DEFAULT_LIMIT=5                    # LIMIT por defecto en queries (máx 100)

Entornos preconfigurados

Hay varios archivos .env.<entorno> para alternar entre bases de datos sin reescribir credenciales:

cp .env.ecosistema-prd .env       # producción
cp .env.ecosistema-tst .env       # testing
cp .env.db-admision-tst .env      # admisión testing
# ...etc.

Recomendación: usa un rol de PostgreSQL de solo lectura (CREATE ROLE ... LOGIN; GRANT USAGE ON SCHEMA ... TO ...; GRANT SELECT ON ALL TABLES IN SCHEMA ... TO ...;). El servidor refuerza READ ONLY, pero la defensa en profundidad importa.

Integración con Claude Code

Opción A — claude mcp add (recomendado)

Pasando credenciales como variables de entorno:

claude mcp add \
  --transport stdio \
  --env DB_HOST=localhost \
  --env DB_PORT=5432 \
  --env DB_NAME=mi_base \
  --env DB_USER=mi_user \
  --env DB_PASSWORD=mi_password \
  --env DB_SCHEMAS=public \
  postgres \
  -- node /ruta/absoluta/al/proyecto/dist/index.js

Tomando el .env del propio repo (omite los --env):

claude mcp add --transport stdio postgres \
  -- node /ruta/absoluta/al/proyecto/dist/index.js

Scope global (disponible en todos los proyectos):

claude mcp add --scope user --transport stdio postgres \
  -- node /ruta/absoluta/al/proyecto/dist/index.js

Opción B — JSON manual

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/ruta/absoluta/al/proyecto/dist/index.js"],
      "env": {
        "DB_HOST": "...",
        "DB_NAME": "...",
        "DB_USER": "...",
        "DB_PASSWORD": "...",
        "DB_SCHEMAS": "public"
      }
    }
  }
}

Integración con Claude Desktop (MCPB)

El proyecto incluye un manifest.json listo para empaquetar como MCPB (Claude Desktop Bundle).

pnpm run build
pnpm run mcpb:pack    # genera mcp_postgres.mcpb en la raíz del repo

El .mcpb es un artefacto de build (está en .gitignore) — se regenera cuando lo necesites. No lo subas al repo.

Qué hacer con mcp_postgres.mcpb

Uso personal (instalarlo en tu Claude Desktop):

1. Abre Claude Desktop → Settings → Extensions
2. Arrastra mcp_postgres.mcpb a la ventana (o usa "Install extension")
3. Claude Desktop te pedirá los datos de conexión (host, user, password, etc.) mediante el formulario definido en user_config del manifest.json — el campo db_password está marcado como sensitive
4. Una vez instalado, puedes borrar el archivo .mcpb local

Distribución privada (compartir con tu equipo):

• Súbelo como release asset en GitHub: gh release create v1.1.0 mcp_postgres.mcpb
• O distribúyelo por un storage interno (S3, Drive, etc.) y comparte el link
• Tus compañeros descargan el .mcpb y lo arrastran a Claude Desktop

Distribución pública: publícalo en el MCP Bundle Directory cuando esté disponible. Mientras tanto, GitHub Releases es el canal estándar.

Si no lo vas a instalar ahora: simplemente bórralo (rm mcp_postgres.mcpb) y regenéralo con pnpm run mcpb:pack cuando lo necesites.

Tools

Todas las tools llevan readOnlyHint: true, destructiveHint: false y outputSchema Zod para structuredContent. Los errores recuperables se devuelven como { isError: true, content }, no como excepciones de protocolo.

Introspección

Tool	Descripción
postgres_list_schemas	Lista esquemas accesibles.
postgres_list_tables	Tablas de un esquema con conteo de columnas (paginado).
postgres_describe_table	Columnas, constraints (PK/FK/UNIQUE) e índices.
postgres_list_functions	Funciones/procedimientos con firma, retorno y lenguaje (paginado).
postgres_list_triggers	Triggers con tabla, evento y timing (paginado).
postgres_get_function_definition	Código fuente de una función (con soporte de sobrecarga).
postgres_get_trigger_definition	Definición completa de un trigger.
postgres_list_views	Vistas regulares y materializadas (paginado).
postgres_search_columns	Busca columnas por nombre/patrón en todos los esquemas permitidos.

Consulta y análisis

Tool	Descripción
postgres_query_table	SELECT seguro sobre una sola tabla con filtros estructurados.
postgres_execute_query	SELECT/WITH avanzado (JOINs, CTEs, agregaciones). Single-statement, READ ONLY.
postgres_explain_query	EXPLAIN / EXPLAIN ANALYZE de un SELECT — perfila planes antes de ejecutar.
postgres_get_table_stats	Tamaño total/tabla/índices/toast, vacuum/analyze, índices con idx_scan = 0.

Las tools paginadas (postgres_list_*) aceptan limit/offset y devuelven has_more/next_offset para iterar.

Resources

URIs navegables que el host puede consumir como contexto:

URI template	Contenido
postgres://schema/{schema}	Resumen del esquema: tablas, vistas, funciones, triggers, conteos.
postgres://table/{schema}/{table}	Estructura completa de una tabla (columnas + constraints + índices).

Prompts

Slash commands disponibles en Claude Code (/mcp__postgres__<prompt>):

Prompt	Argumentos	Propósito
audit-table	schema, table	Auditoría estructurada: schema, storage, sample, triggers, riesgos.
find-tables	pattern	Encuentra columnas/tablas por patrón fuzzy en todos los esquemas.
explain-foreign-keys	schema	Mapa textual del grafo de FKs (hubs, huérfanos).
profile-slow-query	sql	EXPLAIN ANALYZE + recomendaciones priorizadas (índices faltantes, scans, sorts caros).

Ejemplo (en Claude Code):

/mcp__postgres__audit-table schema=public table=users
/mcp__postgres__profile-slow-query sql="SELECT * FROM orders WHERE customer_id IN (SELECT id FROM customers WHERE country='PE')"

Seguridad

• Filtrado de esquemas: DB_SCHEMAS restringe acceso a nivel de aplicación; además postgres_execute_query ajusta search_path local por consulta.
• Query table seguro: postgres_query_table usa columnas/filtros estructurados con parámetros SQL — nunca concatena strings.
• Read-only reforzado: postgres_execute_query y postgres_explain_query corren bajo SET TRANSACTION READ ONLY con statement_timeout = 30s.
• Single-statement: rechaza queries con ; interno y palabras clave de escritura (INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/TRUNCATE/GRANT/REVOKE/EXECUTE/COPY) validadas por regex con \b.
• Cap de filas: máximo 100 filas por consulta; se inyecta o clampa el LIMIT automáticamente.
• TLS seguro por defecto: cuando DB_SSL=true, DB_SSL_REJECT_UNAUTHORIZED=true por defecto.
• Timeouts: 10 s para establecer conexión, 30 s para statement.
• Defensa en profundidad: aun así, usa un rol de PostgreSQL de solo lectura en el DB_USER.

Estructura del proyecto

src/
├── index.ts              # Bootstrap — conecta transport y verifica DB
├── server.ts             # createServer() — instancia McpServer, registra tools/resources/prompts
├── db/
│   └── pool.ts           # Pool, allowedSchemas, defaultLimit, isSchemaAllowed
├── tools/
│   ├── introspection.ts  # list_schemas / list_tables / describe_table / list_views / search_columns
│   ├── objects.ts        # list_functions / list_triggers / get_*_definition
│   ├── query.ts          # query_table / execute_query
│   └── analysis.ts       # explain_query / get_table_stats
├── resources/
│   └── index.ts          # postgres://schema/* y postgres://table/*
├── prompts/
│   └── index.ts          # audit-table / find-tables / explain-foreign-keys / profile-slow-query
└── utils/
    └── response.ts       # formatResult(), assertSchemaAllowed(), CHARACTER_LIMIT

Desarrollo

pnpm run build      # Compila TypeScript → dist/
pnpm run dev        # Watch mode
pnpm start          # Ejecuta el servidor compilado
pnpm run mcpb:pack  # Empaqueta como .mcpb para Claude Desktop

Tras editar cualquier archivo en src/, ejecuta pnpm run build antes de probar cambios. El binario que Claude Code/Desktop lanza es dist/index.js.

Troubleshooting

Error: schema "X" is not allowed — añade X a DB_SCHEMAS (o déjalo vacío para permitir todos los no-sistema).

statement timeout — la query supera 30 s. Usa postgres_explain_query con analyze=false primero, o filtra por una columna indexada.

self-signed certificate en RDS / Supabase — establece DB_SSL=true. Solo baja DB_SSL_REJECT_UNAUTHORIZED=false si el proveedor usa cert auto-firmado.

Claude Code no ve las tools — verifica con claude mcp list que postgres aparece como connected. Si no, claude mcp get postgres te muestra el comando registrado; comprueba que la ruta absoluta a dist/index.js es correcta y que el build está actualizado.

Query devuelve has_more: true — vuelve a llamar la tool pasando offset = next_offset. Las listas están paginadas para no inflar el contexto.

Licencia

MIT