Simple PostgreSQL MCP Server

Servidor MCP PostgreSQL simple

Este es un proyecto de plantilla para quienes buscan construir sus propios servidores MCP. Lo diseñé para que fuera muy fácil de entender y adaptar: el código es claro e incluye documentación de MCP para que puedas ponerte al día rápidamente.

¿Qué es MCP?

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

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

• Las herramientas permiten que el LLM ejecute comandos (como ejecutar una consulta de base de datos)
• Los recursos son datos que puedes adjuntar a las conversaciones (como adjuntar un archivo a una solicitud)
• Las indicaciones son plantillas que generan instrucciones LLM consistentes

Características

Este servidor PostgreSQL MCP implementa:

1. Herramientas
   • execute_query - Ejecuta consultas SQL en tu base de datos
   • test_connection - Verifica que la conexión a la base de datos esté funcionando
2. Recursos
   • db://tables - Lista de todas las tablas del 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 de la base de datos
3. Indicaciones
   • Plantillas de generación de consultas
   • Constructores de consultas analíticas
   • Basado en las plantillas de este repositorio

Prerrequisitos

• Python 3.8+
• uv - Administrador e instalador de paquetes de Python moderno
• npx (incluido con Node.js)
• Base de datos PostgreSQL a la que puede conectarse

Configuración rápida

1. Cree un entorno virtual e instale 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
2. Ejecute el servidor con el Inspector 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 ejecuta npx, se le solicitará que apruebe la instalación. Escriba "y" para continuar.

   Después de ejecutar este comando, verá la interfaz del Inspector MCP abierta en su navegador. Debería ver un mensaje como este:
   MCP Inspector is up and running at http://localhost:5173
   Si el navegador no se abre automáticamente, copia y pega la URL. Deberías ver algo como esto:
3. Usando el Inspector:
   • Haga clic en el botón "Conectar" en la interfaz (a menos que haya un mensaje de error en la consola en la parte inferior izquierda)
   • Explora las pestañas "Herramientas", "Recursos" y "Avisos" para ver las funciones disponibles.
   • Intente hacer clic en los comandos enumerados o escribir los nombres de los recursos para recuperar recursos y avisos
   • La interfaz le permite probar consultas y ver cómo responde el servidor MCP
4. Echa un vistazo a los documentos oficialesGuía oficial para desarrolladores de servidores: https://modelcontextprotocol.io/quickstart/serverMás información sobre el inspector: https://modelcontextprotocol.io/docs/tools/inspector

Conecte su herramienta de IA al servidor

Puede configurar el servidor MCP para su asistente de IA creando un archivo de configuración MCP:

Alternativamente, puede generar este archivo de configuración utilizando el script incluido:

Cuando se le solicite, ingrese su 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 de mi base de datos?"
• "Muéstrame los 5 mejores usuarios por fecha de creación"
• "Contar direcciones por estado"

Para realizar pruebas, Claude Desktop admite MCP de forma nativa y funciona con todas las funciones (herramientas, recursos y avisos) desde el primer momento.

Base de datos de ejemplo (opcional)

Si no tiene una base de datos lista o tiene problemas de conexión, puede utilizar la base de datos de ejemplo incluida:

Este script crea un contenedor Docker con una base de datos PostgreSQL precargada con tablas de usuarios y direcciones de ejemplo. Tras su ejecución, puede conectarse mediante:

Próximos pasos

Para ampliar este proyecto con sus propios servidores MCP:

1. Cree un nuevo directorio en /src (por ejemplo, /src/my-new-mcp )
2. Implemente su servidor MCP siguiendo el ejemplo de PostgreSQL
3. Agregue su nuevo MCP a pyproject.toml :

Luego puedes ejecutar tu nuevo MCP con:

Documentación

• Se incluyen documentos MCP para facilitar el desarrollo del LLM
• Basado en el enfoque en: https://modelcontextprotocol.io/tutorials/building-mcp-with-llms

Seguridad

Este es un proyecto experimental que permite a los desarrolladores crear su propio servidor MCP. Hice lo mínimo para asegurarme de que no se bloquee inmediatamente al probarlo, pero ten cuidado: es muy fácil ejecutar inyecciones SQL con esta herramienta. El servidor comprobará si la consulta comienza con SELECT, pero más allá de eso, no hay garantía. En resumen: no lo ejecutes en producción a menos que seas el fundador y no haya clientes que paguen.

Licencia

Instituto Tecnológico de Massachusetts (MIT)