Simple PostgreSQL MCP Server

Un servidor MCP para interactuar con bases de datos PostgreSQL mediante herramientas, recursos y prompts.

Documentación

Servidor MCP Simple de PostgreSQL

Este es un proyecto plantilla para aquellos que buscan construir sus propios servidores MCP. Lo diseñé para que sea extremadamente simple de entender y adaptar: el código es directo con documentación de MCP adjunta para que puedas ponerte al día rápidamente.

¿Qué es MCP?

TL;DR - Es una forma de escribir plugins para IA

El Protocolo de Contexto de Modelos (MCP) es una forma estándar para que los LLMs interactúen con herramientas y datos externos. En resumen:

Herramientas permiten al LLM ejecutar comandos (como ejecutar una consulta de base de datos)
Recursos son datos que puedes adjuntar a conversaciones (como adjuntar un archivo a un prompt)
Prompts son plantillas que generan instrucciones consistentes para LLMs

Características

Este servidor MCP de PostgreSQL implementa:

Herramientas
- execute_query - Ejecutar consultas SQL contra tu base de datos
- test_connection - Verificar que la conexión a la base de datos funciona
Recursos
- db://tables - Lista de todas las tablas en el esquema
- db://tables/{table_name} - Información del esquema para una tabla específica
- db://schema - Información completa del esquema para todas las tablas en la base de datos
Prompts
- Plantillas de generación de consultas
- Constructores de consultas analíticas
- Basados en las plantillas de este repositorio

Requisitos previos

Python 3.8+
uv - Gestor e instalador de paquetes de Python moderno
npx (incluido con Node.js)
Base de datos PostgreSQL a la que puedas conectarte

Configuración rápida

Crea un entorno virtual e instala las dependencias:

# Create a virtual environment with uv
uv venv

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -r requirements.txt

Ejecuta el servidor con el Inspector de MCP:
```
# Replace with YOUR actual database credentials
npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://username:password@hostname:port/database -e SCHEMA=public
```
Nota: Si es la primera vez que ejecutas npx, se te pedirá que apruebes la instalación. Escribe 'y' para continuar.

Después de ejecutar este comando, verás la interfaz del Inspector de MCP abierta en tu navegador. Deberías ver un mensaje como:
```
MCP Inspector is up and running at http://localhost:5173
```
Si el navegador no se abre automáticamente, copia y pega la URL en tu navegador. Deberías ver algo como esto:
Usando el Inspector:
- Haz clic en el botón "Connect" en la interfaz (a menos que haya un mensaje de error en la consola en la parte inferior izquierda)
- Explora las pestañas "Tools", "Resources" y "Prompts" para ver la funcionalidad disponible
- Intenta hacer clic en los comandos listados o escribe nombres de recursos para recuperar recursos y prompts
- La interfaz te permite probar consultas y ver cómo responde el servidor MCP
Echa un vistazo a la documentación oficial

Guía oficial para desarrolladores de servidores: https://modelcontextprotocol.io/quickstart/server

Más sobre el inspector: https://modelcontextprotocol.io/docs/tools/inspector

Conecta tu Herramienta de IA al Servidor

Puedes configurar el servidor MCP para tu asistente de IA creando un archivo de configuración MCP:

{
   "mcpServers": {
      "postgres": {
         "command": "/path/to/uv",
         "args": [
            "--directory",
            "/path/to/simple-psql-mcp",
            "run",
            "postgres"
         ],
         "env": {
            "DSN": "postgresql://username:password@localhost:5432/my-db",
            "SCHEMA": "public"
         }
      }
   }
}

Alternativamente, puedes generar este archivo de configuración usando el script incluido:

# Make the script executable
chmod +x generate_mcp_config.sh

# Run the configuration generator
./generate_mcp_config.sh

Cuando se te solicite, ingresa tu DSN de PostgreSQL y el nombre del esquema.

Cómo usarlo

Ahora puedes hacer preguntas al LLM sobre tus datos en lenguaje natural:

"¿Cuáles son todas las tablas en mi base de datos?"
"Muéstrame los 5 usuarios principales por fecha de creación"
"Cuenta las direcciones por estado"

Para pruebas, Claude Desktop soporta MCP de forma nativa y funciona con todas las características (herramientas, recursos y prompts) directamente.

Base de Datos de Ejemplo (Opcional)

Si no tienes una base de datos lista o encuentras problemas de conexión, puedes usar la base de datos de ejemplo incluida:

# Make the script executable
chmod +x example-db/create-db.sh

# Run the database setup script
./example-db/create-db.sh

Este script crea un contenedor Docker con una base de datos PostgreSQL pre-poblada con tablas de ejemplo de usuarios y direcciones. Después de ejecutarlo, puedes conectarte usando:

npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://postgres:postgres@localhost:5432/user_database -e SCHEMA=public

Próximos Pasos

Para extender este proyecto con tus propios servidores MCP:

Crea un nuevo directorio bajo /src (por ejemplo, /src/my-new-mcp)
Implementa tu servidor MCP siguiendo el ejemplo de PostgreSQL
Agrega tu nuevo MCP a pyproject.toml:

[project.scripts]
postgres = "src.postgres:main"
my-new-mcp = "src.my-new-mcp:main"

Luego puedes ejecutar tu nuevo MCP con:

npx @modelcontextprotocol/inspector uv --directory . run my-new-mcp

Documentación

Documentación de MCP incluida para facilitar el desarrollo de LLMs
Basado en el enfoque de: https://modelcontextprotocol.io/tutorials/building-mcp-with-llms

Seguridad

Este es un proyecto experimental destinado a empoderar a los desarrolladores para crear su propio servidor MCP. Hice lo mínimo para asegurar que no falle inmediatamente cuando lo pruebes, pero ten cuidado: es muy fácil ejecutar inyecciones SQL con esta herramienta. El servidor verificará si la consulta comienza con SELECT, pero más allá de eso nada está garantizado. TL;DR - no lo ejecutes en producción a menos que seas el fundador y no haya clientes que paguen.

Licencia

MIT