MCP PostgreSQL Server

Un servidor MCP (Model Context Protocol) seguro para acceder a bases de datos PostgreSQL que solo permite consultas SELECT.

🚀 Características

• ✅ Solo consultas SELECT: Máxima seguridad, no permite INSERT, UPDATE, DELETE u otras operaciones peligrosas
• ✅ Configuración desde el proyecto: Lee la cadena de conexión desde MCP_PG_CONNSTR en el archivo .env del proyecto que está siendo editado (no del servidor MCP)
• ✅ JavaScript puro: No requiere TypeScript ni compilación
• ✅ Manejo robusto de errores: Logging apropiado y manejo de errores de conexión
• ✅ Múltiples herramientas útiles: Exploración de esquemas, listado de tablas, y consultas comunes

📁 Concepto importante: Separación de configuración

Este servidor MCP funciona de manera diferente a una aplicación normal:

📂 Tu proyecto (donde trabajas)
├── 📄 .env                    ← Aquí va MCP_PG_CONNSTR
├── 📂 src/
├── 📄 package.json
└── 📄 README.md

📂 Servidor MCP (instalado por separado)
├── 📄 index.js               ← El servidor MCP
├── 📄 package.json
└── 📄 README.md

¿Por qué es así?

• El servidor MCP es una herramienta externa que se conecta a tu proyecto
• Cada proyecto puede tener su propia base de datos (diferente conexión)
• El servidor MCP lee automáticamente el .env de tu proyecto actual
• No necesitas configurar nada en el servidor MCP, solo en tu proyecto

📋 Requisitos previos

• Node.js 18 o superior
• Una base de datos PostgreSQL accesible
• Acceso de lectura a la base de datos

🛠️ Instalación

1. Clona o descarga el proyecto:

git clone <repository-url>
cd postgres

2. Instala las dependencias:

npm install

3. Configura las variables de entorno EN EL PROYECTO QUE ESTÁS EDITANDO:

⚠️ IMPORTANTE: El archivo .env debe estar en la raíz del proyecto que estás editando, NO en la carpeta del servidor MCP.

En la raíz de tu proyecto (donde tienes tu código fuente), crea un archivo .env:

# En la raíz de tu proyecto (no en la carpeta del servidor MCP)
MCP_PG_CONNSTR=postgresql://usuario:contraseña@localhost:5432/basededatos

Ejemplo de estructura:

mi-proyecto/              ← Tu proyecto
├── .env                  ← Aquí va el archivo .env
├── src/
├── package.json
└── ...

mcp-postgres-server/      ← Servidor MCP (separado)
├── index.js
├── package.json
└── ...

🚀 Uso

Ejecución del servidor

# Modo normal
npm start

# Modo desarrollo (con reinicio automático)
npm run dev

Configuración en Claude Desktop

Para usar este servidor con Claude Desktop, agrega la siguiente configuración a tu archivo claude_desktop_config.json:

Windows:

{
  "mcpServers": {
    "postgresql": {
      "command": "node",
      "args": ["C:\\ruta\\completa\\hacia\\postgres\\index.js"],
      "cwd": "C:\\ruta\\completa\\hacia\\postgres"
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "postgresql": {
      "command": "node",
      "args": ["/ruta/completa/hacia/postgres/index.js"],
      "cwd": "/ruta/completa/hacia/postgres"
    }
  }
}

Ubicación del archivo de configuración:

• Windows: %APPDATA%\\Claude\\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

🔧 Herramientas disponibles

1. execute_select_query

Ejecuta consultas SELECT personalizadas.

Parámetros:

• query (string): La consulta SELECT a ejecutar
• params (array, opcional): Parámetros para consultas preparadas

Ejemplo:

SELECT * FROM usuarios WHERE edad > $1 ORDER BY nombre;

2. list_tables

Lista todas las tablas disponibles en la base de datos.

Parámetros: Ninguno

3. describe_table

Obtiene información detallada sobre las columnas de una tabla.

Parámetros:

• table_name (string): Nombre de la tabla
• schema_name (string, opcional): Nombre del esquema (por defecto: 'public')

4. execute_common_queries

Ejecuta consultas predefinidas útiles.

Parámetros:

• query_type (string): Uno de:
  • database_version: Versión de PostgreSQL
  • current_user: Usuario actual
  • current_database: Base de datos actual
  • table_sizes: Tamaños de las tablas

🔒 Seguridad

Este servidor implementa múltiples capas de seguridad:

1. Validación de consultas: Solo permite comandos SELECT
2. Filtrado de patrones peligrosos: Bloquea INSERT, UPDATE, DELETE, DROP, etc.
3. Consultas preparadas: Soporte para parámetros seguros
4. Conexiones seguras: Soporte SSL para conexiones en producción

Consultas permitidas ✅

SELECT * FROM usuarios;
SELECT COUNT(*) FROM pedidos WHERE fecha > '2024-01-01';
SELECT u.nombre, p.total FROM usuarios u JOIN pedidos p ON u.id = p.usuario_id;

Consultas bloqueadas ❌

INSERT INTO usuarios (nombre) VALUES ('nuevo');
UPDATE usuarios SET email = 'nuevo@email.com';
DELETE FROM usuarios WHERE id = 1;
DROP TABLE usuarios;

🌍 Variables de entorno

⚠️ Ubicación importante: Estas variables deben estar en el archivo .env en la raíz del proyecto que estás editando, no en la carpeta del servidor MCP.

Variable	Descripción	Ubicación	Ejemplo
MCP_PG_CONNSTR	Cadena de conexión a PostgreSQL	Proyecto editado/.env	postgresql://user:pass@localhost:5432/db
PORT	Puerto para servidor HTTP (opcional)	Proyecto editado/.env	3000
NODE_ENV	Entorno de ejecución	Proyecto editado/.env	production

🔄 Ejemplos de cadenas de conexión

PostgreSQL local:

MCP_PG_CONNSTR=postgresql://postgres:password@localhost:5432/mydatabase

PostgreSQL remoto:

MCP_PG_CONNSTR=postgresql://username:password@hostname:5432/database_name

Con SSL:

MCP_PG_CONNSTR=postgresql://username:password@hostname:5432/database_name?sslmode=require

Con parámetros adicionales:

MCP_PG_CONNSTR=postgresql://user:pass@host:5432/db?application_name=mcp-server&connect_timeout=10

🐛 Solución de problemas

Error: "MCP_PG_CONNSTR no está definida"

• IMPORTANTE: El archivo .env debe estar en la raíz del proyecto que estás editando, NO en la carpeta del servidor MCP
• El servidor busca en [directorio-de-tu-proyecto]/.env
• Verifica que la variable MCP_PG_CONNSTR está definida correctamente en ese archivo
• Revisa el mensaje de error que muestra la ruta exacta donde busca el archivo

Error de conexión a la base de datos

• Verifica que PostgreSQL está ejecutándose
• Confirma que las credenciales son correctas
• Asegúrate de que el usuario tiene permisos de lectura en las tablas

El servidor no aparece en Claude Desktop

• Verifica que las rutas en claude_desktop_config.json son absolutas y correctas
• Reinicia Claude Desktop después de modificar la configuración
• Revisa los logs de error en la consola

Problemas de permisos

-- Otorgar permisos de lectura al usuario
GRANT SELECT ON ALL TABLES IN SCHEMA public TO tu_usuario;
GRANT USAGE ON SCHEMA public TO tu_usuario;

📝 Logs y depuración

El servidor usa console.error() para logging, que es seguro con el transporte STDIO de MCP. Los logs incluyen:

• ✅ Confirmación de conexión exitosa a PostgreSQL
• 🔍 Consultas ejecutadas (primeros 100 caracteres)
• ❌ Errores de conexión y consultas
• 📊 Información de inicio del servidor

🤝 Contribución

1. Fork del repositorio
2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
3. Commit tus cambios (git commit -am 'Agrega nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Crea un Pull Request

📄 Licencia

MIT License - ver archivo LICENSE para más detalles.

🔗 Enlaces útiles

• Model Context Protocol
• Documentación de PostgreSQL
• Claude Desktop
• node-postgres (pg)

📞 Soporte

Si encuentras algún problema o tienes sugerencias, por favor:

1. Revisa la sección de solución de problemas
2. Busca en los issues existentes
3. Crea un nuevo issue si es necesario

---

⚠️ Recordatorio de seguridad: Este servidor solo permite consultas SELECT para mantener la seguridad de tu base de datos. No modifica, elimina ni altera datos de ninguna manera.