PostgreSQL MCP Server

Un servidor MCP que proporciona herramientas para interactuar con bases de datos PostgreSQL.

Documentación

PostgreSQL MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona herramientas para interactuar con bases de datos PostgreSQL. Construido con el Kotlin MCP SDK oficial para un cumplimiento robusto y estandarizado del protocolo.

Características

🔒 Ejecución Segura de Consultas: Solo se permiten consultas SELECT por seguridad
🗄️ Inspección de Esquemas: Obtén esquemas detallados de tablas e información de columnas
📋 Listado de Tablas: Lista todas las tablas de la base de datos
🔗 Descubrimiento de Relaciones: Descubre claves foráneas, claves primarias y relaciones entre tablas
🔄 Sugerencias de JOIN: Obtén sugerencias inteligentes de consultas JOIN basadas en relaciones
🌍 Soporte Multi-Entorno: Conéctate a bases de datos de staging, release y producción
⚡ Pool de Conexiones HikariCP: Gestión de conexiones de nivel empresarial
📊 Monitoreo en Tiempo Real: Estadísticas integradas del pool de conexiones y monitoreo de salud

Requisitos Previos

Java 17 o superior
Base(s) de datos PostgreSQL
Archivo de configuración de base de datos (database.properties)

Herramientas Disponibles

Nombre de la Herramienta	Descripción	Parámetros Requeridos	Parámetros Opcionales	Devuelve
`postgres_query`	Ejecuta consultas SELECT contra la base de datos	`sql` (string)	`environment` (staging/release/production)	Resultados de la consulta en formato de tabla
`postgres_list_tables`	Lista todas las tablas de la base de datos	Ninguno	`environment` (staging/release/production)	Lista de nombres de tablas
`postgres_get_table_schema`	Obtén información detallada del esquema de una tabla	`table_name` (string)	`environment` (staging/release/production)	Detalles de columnas con tipos de datos, restricciones e indicadores de relaciones
`postgres_get_relationships`	Obtén relaciones de tablas (FK, PK, restricciones)	`table_name` (string)	`environment` (staging/release/production)	Claves primarias, claves foráneas, referenciado por, restricciones únicas
`postgres_suggest_joins`	Sugiere consultas JOIN basadas en relaciones	`table_name` (string)	`environment` (staging/release/production)	Condiciones JOIN sugeridas y consultas de ejemplo
`postgres_get_database_info`	Obtén el nombre de la base de datos e información de conexión	Ninguno	`environment` (staging/release/production)	Nombre de la base de datos, versión, información del driver y detalles de conexión
`postgres_connection_stats`	Obtén estadísticas del pool de conexiones e información de salud	Ninguno	Ninguno	Estado del pool HikariCP, métricas e información de salud

Características de Seguridad

🔒 Acceso de Solo Lectura: Solo se permiten consultas SELECT
🛡️ Protección contra Inyección SQL: Utiliza consultas parametrizadas cuando es posible
📏 Límite de Filas: Límites configurables evitan respuestas abrumadoras
✅ Validación de Conexión: Pruebas y validación de conexión integradas

Configuración

Crea un archivo database.properties en src/main/resources/ con los detalles de conexión de tu base de datos:

# PostgreSQL Database Configuration
# All sensitive information should be provided via environment variables

# Staging Environment
database.staging.jdbc-url=${POSTGRES_STAGING_JDBC_URL}
database.staging.username=${POSTGRES_STAGING_USERNAME}
database.staging.password=${POSTGRES_STAGING_PASSWORD}

# Release Environment
database.release.jdbc-url=${POSTGRES_RELEASE_JDBC_URL}
database.release.username=${POSTGRES_RELEASE_USERNAME}
database.release.password=${POSTGRES_RELEASE_PASSWORD}

# Production Environment
database.production.jdbc-url=${POSTGRES_PRODUCTION_JDBC_URL}
database.production.username=${POSTGRES_PRODUCTION_USERNAME}
database.production.password=${POSTGRES_PRODUCTION_PASSWORD}

# HikariCP Connection Pool Configuration (Optional)
# Uses sensible defaults if not specified

# Optional: Override default pool sizes per environment
hikari.staging.maximum-pool-size=5
hikari.staging.minimum-idle=1

hikari.release.maximum-pool-size=8
hikari.release.minimum-idle=2

hikari.production.maximum-pool-size=15
hikari.production.minimum-idle=3

Configuración de Variables de Entorno

Establece las variables de entorno requeridas para tus conexiones de base de datos:

# Staging Environment
export POSTGRES_STAGING_JDBC_URL="jdbc:postgresql://localhost:5432/mydb_staging"
export POSTGRES_STAGING_USERNAME="your_staging_username"
export POSTGRES_STAGING_PASSWORD="your_staging_password"

# Release Environment
export POSTGRES_RELEASE_JDBC_URL="jdbc:postgresql://localhost:5432/mydb_release"
export POSTGRES_RELEASE_USERNAME="your_release_username"
export POSTGRES_RELEASE_PASSWORD="your_release_password"

# Production Environment
export POSTGRES_PRODUCTION_JDBC_URL="jdbc:postgresql://prod-host:5432/mydb_production"
export POSTGRES_PRODUCTION_USERNAME="your_production_username"
export POSTGRES_PRODUCTION_PASSWORD="your_production_password"

Para Windows (PowerShell):

$env:POSTGRES_STAGING_JDBC_URL="jdbc:postgresql://localhost:5432/mydb_staging"
$env:POSTGRES_STAGING_USERNAME="your_staging_username"
$env:POSTGRES_STAGING_PASSWORD="your_staging_password"
# ... repeat for release and production

Para entornos Docker/Contenedores:

environment:
  - POSTGRES_STAGING_JDBC_URL=jdbc:postgresql://localhost:5432/mydb_staging
  - POSTGRES_STAGING_USERNAME=your_staging_username
  - POSTGRES_STAGING_PASSWORD=your_staging_password

Compilación

El sistema de compilación requiere un parámetro jarSuffix para crear archivos JAR específicos de la base de datos:

# Build JAR for specific database system
./gradlew shadowJar -PjarSuffix=incidents
./gradlew shadowJar -PjarSuffix=users
./gradlew shadowJar -PjarSuffix=analytics
./gradlew shadowJar -PjarSuffix=payroll

Esto crea archivos JAR con nombres descriptivos:

build/libs/postgres-mcp-tool-incidents.jar
build/libs/postgres-mcp-tool-users.jar
build/libs/postgres-mcp-tool-analytics.jar
build/libs/postgres-mcp-tool-payroll.jar

Nota: El parámetro jarSuffix es obligatorio. Ejecutar ./gradlew shadowJar sin él fallará con un mensaje de error claro.

Flujo de Trabajo Multi-Base de Datos

Esta convención de nombres te permite gestionar múltiples sistemas de bases de datos de manera eficiente:

Configura tu database.properties para el sistema de base de datos objetivo
Compila el JAR con un sufijo descriptivo: ./gradlew shadowJar -PjarSuffix=incidents
Repite para otros sistemas de bases de datos (usuarios, analítica, nóminas, etc.)
Despliega múltiples servidores MCP, cada uno con su propio JAR y configuración de base de datos
Distingue fácilmente entre diferentes conexiones de base de datos en tu agente de IA

Ejemplo de Flujo de Trabajo:

# Configure database.properties for incidents database
# Build incidents JAR
./gradlew shadowJar -PjarSuffix=incidents

# Update database.properties for users database
# Build users JAR
./gradlew shadowJar -PjarSuffix=users

# Update database.properties for analytics database
# Build analytics JAR
./gradlew shadowJar -PjarSuffix=analytics

Enrutamiento de Base de Datos por Entorno

Todas las herramientas admiten enrutamiento de base de datos por entorno con un parámetro opcional environment:

staging (predeterminado) - Enruta a la base de datos de staging
release - Enruta a la base de datos de release
production - Enruta a la base de datos de producción

Soporte de Lenguaje Natural

Los agentes de IA extraen automáticamente la información del entorno de las indicaciones del usuario:

"Consulta la base de datos de producción para estadísticas de usuarios" → environment: "production"
"Lista las tablas en staging" → environment: "staging"
"Muéstrame el esquema de la tabla de usuarios en release" → environment: "release"

Uso con Agentes de IA

Añade esta configuración al archivo de configuración MCP de tu agente de IA:

Configuración de Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "postgres-incidents": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-incidents.jar"]
    },
    "postgres-users": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-users.jar"]
    },
    "postgres-analytics": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-analytics.jar"]
    }
  }
}

Configuración de Base de Datos Única:

{
  "mcpServers": {
    "postgres-mcp-tool": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-incidents.jar"]
    }
  }
}

Configuración del Plugin Augment IntelliJ

En el plugin Augment IntelliJ, añade servidores MCP para cada sistema de base de datos:

Para la Base de Datos de Incidentes:

Nombre: postgres-incidents
Comando: java -jar /absolute/path/to/postgres-mcp-tool-incidents.jar

Para la Base de Datos de Usuarios:

Nombre: postgres-users
Comando: java -jar /absolute/path/to/postgres-mcp-tool-users.jar

Para la Base de Datos de Analítica:

Nombre: postgres-analytics
Comando: java -jar /absolute/path/to/postgres-mcp-tool-analytics.jar

Otros Agentes de IA

Para otros agentes de IA compatibles con MCP, utiliza el formato estándar de configuración de servidor MCP:

Sistemas de Múltiples Bases de Datos:

[
  {
    "name": "postgres-incidents",
    "command": "java",
    "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-incidents.jar"],
    "env": {}
  },
  {
    "name": "postgres-users",
    "command": "java",
    "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-users.jar"],
    "env": {}
  }
]

Sistema de Base de Datos Única:

{
  "name": "postgres-mcp-tool",
  "command": "java",
  "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-incidents.jar"],
  "env": {}
}

Requisitos Previos

Antes de usar el servidor MCP, asegúrate de tener:

Java 17+ instalado y disponible en tu PATH
Compilado el archivo JAR usando ./gradlew shadowJar -PjarSuffix=<database-name>
Establecidas las variables de entorno para tus conexiones de base de datos (consulta la Configuración de Variables de Entorno arriba)
Permisos de base de datos - el usuario configurado debe tener permisos SELECT en las bases de datos objetivo

Gestión de JAR Específicos de Base de Datos

Dado que puedes crear múltiples archivos JAR para diferentes sistemas de bases de datos, puedes:

Compilar JARs separados para cada sistema de base de datos (incidentes, usuarios, analítica, etc.)
Configurar diferentes database.properties para cada sistema antes de compilar
Desplegar múltiples servidores MCP simultáneamente, cada uno conectándose a diferentes bases de datos
Distinguir fácilmente entre conexiones de base de datos usando nombres de JAR descriptivos

Arquitectura

Este servidor está construido usando:

Kotlin MCP SDK v0.5.0: Implementación oficial del Model Context Protocol
HikariCP: Pool de conexiones JDBC de alto rendimiento
PostgreSQL JDBC Driver: Conectividad de base de datos
Kotlinx Serialization: Manejo de JSON
Kotlinx Coroutines: Operaciones asíncronas

Gestión de Conexiones (HikariCP)

Pool de Nivel Empresarial: Gestión de conexiones probada en batalla
Monitoreo Automático de Salud: Validación de conexión y comprobaciones de salud integradas
Detección de Fugas de Conexión: Detecta y reporta automáticamente fugas de conexión
Rendimiento Optimizado: El pool de conexiones más rápido disponible para Java/Kotlin
Operaciones Seguras para Hilos: El acceso concurrente se gestiona adecuadamente

Ejemplos de Uso

Exploración Básica de la Base de Datos

"¿A qué base de datos estoy conectado?"
"¿Qué tablas hay en mi base de datos?"
"Muéstrame el esquema de la tabla de usuarios"
"Consulta las primeras 10 filas de la tabla de productos"

Consultas Específicas por Entorno

"¿Qué tablas hay en la base de datos de producción?"
"Consulta la base de datos de staging para estadísticas de usuarios"
"Muéstrame el esquema de la tabla de pedidos en el entorno de release"
"Obtén las relaciones de la tabla de usuarios en staging"

Descubrimiento de Relaciones

"¿Cuáles son las relaciones de la tabla de pedidos?"
"Muéstrame todas las claves foráneas en la tabla de clientes"
"¿Qué tablas referencian la tabla de usuarios?"
"¿Qué consultas JOIN puedo escribir con la tabla de pedidos?"

Análisis Avanzado de Esquemas

"Muéstrame el esquema completo con relaciones para la tabla de productos"
"¿Cuáles son las claves primarias y foráneas de todas mis tablas?"
"Ayúdame a entender cómo están conectadas mis tablas"

Estructura del Proyecto

postgres-mcp-tool/
├── src/
│   ├── main/
│   │   ├── kotlin/
│   │   │   ├── PostgreSqlMcpServer.kt         # Main MCP server implementation
│   │   │   ├── PostgreSqlRepository.kt        # Database operations and queries
│   │   │   ├── HikariConnectionManager.kt     # Connection pool management
│   │   │   └── DatabaseConnectionConfig.kt    # Database configuration DTO
│   │   └── resources/
│   │       └── database.properties            # Database configuration
│   └── test/kotlin/
│       ├── PostgreSqlMcpServerTest.kt         # Integration tests
│       ├── DatabaseConnectionConfigTest.kt    # DTO unit tests
│       └── DatabaseConfigurationTest.kt       # Configuration integration tests
├── build.gradle.kts                           # Build configuration
├── docker-compose.yml                         # Docker setup for testing
├── init.sql                                   # Sample database schema
└── README.md                                 # This documentation

Solución de Problemas

Problemas Comunes

Conexión Fallida:
- Verifica que todas las variables de entorno requeridas estén establecidas
- Verifica el formato de la URL JDBC: jdbc:postgresql://host:port/database
- Asegúrate de que las credenciales de la base de datos sean correctas
Variables de Entorno No Encontradas:
- Verifica que las variables de entorno estén exportadas en tu shell
- Para agentes de IA, asegúrate de que las variables de entorno estén disponibles para el proceso Java
Permiso Denegado: Asegúrate de que el usuario de la base de datos tenga permisos SELECT
Herramienta No Visible: Verifica la ruta del JAR en la configuración MCP de tu agente de IA
Java No Encontrado: Asegúrate de que Java 17+ esté instalado y en tu PATH
Compilación Fallida - Falta jarSuffix:
- Usa ./gradlew shadowJar -PjarSuffix=<database-name> en lugar de ./gradlew shadowJar
- El parámetro jarSuffix es obligatorio para crear nombres de JAR descriptivos
Conexión de Base de Datos Incorrecta:
- Verifica que estás usando el archivo JAR correcto para el sistema de base de datos previsto
- Comprueba que el nombre del archivo JAR coincida con tu sistema de base de datos (por ejemplo, postgres-mcp-tool-incidents.jar para la base de datos de incidentes)

Depuración

Revisa los registros de tu agente de IA para ver errores. Por ejemplo:

Claude Desktop:

# macOS/Linux
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
# Check %APPDATA%\Claude\Logs\

Otros Agentes de IA:

Consulta la documentación de tu agente de IA específico para conocer las ubicaciones de los registros
Busca mensajes de error relacionados con MCP en la consola o los archivos de registro del agente

Migración al Kotlin MCP SDK

🎉 Actualizado: Este servidor ha sido migrado de una implementación JSON-RPC personalizada al Kotlin MCP SDK oficial, proporcionando:

Beneficios de la Migración

Mejor Cumplimiento del Protocolo: Adherencia total a la especificación MCP
Manejo de Errores Mejorado: Respuestas de error estandarizadas y mejor depuración
Estructura de Código Más Limpia: Código más mantenible y legible
Compatibilidad a Prueba de Futuro: Actualizaciones automáticas con los cambios del protocolo MCP
Rendimiento Mejorado: Capa de transporte optimizada y manejo de mensajes

Qué Cambió

Implementación del Servidor: Ahora usa la clase Server del SDK oficial
Registro de Herramientas: Las herramientas se registran usando el método server.addTool()
Capa de Transporte: Usa StdioServerTransport con la integración adecuada de kotlinx.io
Manejo de Mensajes: Manejo automático del protocolo JSON-RPC por el SDK

Qué Permaneció Igual

Toda la funcionalidad existente: Cada herramienta y característica se ha conservado
Operaciones de base de datos: La gestión de conexiones HikariCP no ha cambiado
Configuración: database.properties limpio con formato simplificado
Compatibilidad de API: Todos los parámetros y respuestas de las herramientas permanecen idénticos

Detalles Técnicos

Versión del SDK: Usando Kotlin MCP SDK v0.5.0
Transporte: Transporte STDIO con flujos kotlinx.io almacenados en búfer
Capacidades: Herramientas con soporte listChanged
Manejo de Errores: Respuestas de error MCP estandarizadas

Esta migración garantiza que el servidor permanezca compatible con todos los clientes MCP mientras se beneficia de las mejoras y actualizaciones futuras del SDK oficial.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.