postgres-mcp

Un servidor MCP genérico y reutilizable para consultas de solo lectura de cualquier base de datos Postgres a través de Claude (o de cualquier cliente compatible con MCP). No conoce ningún esquema concreto: list_tables, describe_table y run_sql funcionan exclusivamente sobre information_schema y la introspección genérica de jsonb, por lo que puede apuntarse a cualquier base de datos Postgres sin cambios en el código.

Modelo de seguridad

Dos capas independientes, defensa en profundidad:

1. A nivel de base de datos: el servidor se conecta con un rol al que solo se ha concedido SELECT; no puede escribir aunque una consulta lo intentara. Crea este rol con setup_reader_role.sql.

2. A nivel de aplicación: run_sql() rechaza cualquier cosa que no sea un SELECT simple (o WITH ... SELECT), impone un límite de 200 filas y establece un tiempo máximo de ejecución de 5 segundos, todo ello como una comprobación rápida de fallo antes incluso de llegar a la base de datos.

Related MCP server: pg-mcp

Configuración

1. Crea un rol de solo lectura en tu base de datos de destino:

   • Abre setup_reader_role.sql, sustituye el marcador de posición de la contraseña y <your_db_name> por valores reales y ejecútalo una vez contra tu base de datos (por ejemplo, mediante psql o una consola SQL de tu proveedor).

2. Configura tu cadena de conexión en un archivo .env en este directorio:

   DATABASE_URL=postgresql://mcp_reader:yourpassword@host:5432/yourdb
   ANTHROPIC_API_KEY=sk-ant-...

   (ANTHROPIC_API_KEY solo es necesaria para chat.py, no para el propio servidor MCP.)

3. Instala las dependencias:

   pip install -r requirements.txt

Pruebas locales

Primero prueba la capa de consulta directamente, sin ningún cliente MCP en el bucle:

python chat.py "what tables do I have?"

Después pruébalo como un servidor MCP real con el Inspector:

fastmcp dev inspector mcp_server.py

Si el conjunto de herramientas de Node del Inspector te da problemas (esto ha ocurrido antes), recurre a ejecutar el servidor directamente por HTTP y probándolo con el cliente Python de FastMCP:

fastmcp run mcp_server.py --transport http --port 8000

from fastmcp import Client
import asyncio

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        print(await client.call_tool("list_tables", {}))

asyncio.run(main())

Despliegue (Prefect Horizon)

La plataforma de despliegue alojado de FastMCP se llama actualmente Prefect Horizon (anteriormente era «FastMCP Cloud»); el nombre ya ha cambiado antes, así que verifica el nombre y la URL actuales en gofastmcp.com/deployment antes de seguir estos pasos, por si hubiera vuelto a cambiar.

1. Sube este repositorio a GitHub; primero debe existir un remoto real (consulta los comandos de git al final de este README si aún no lo has hecho).

2. Ve a la página de la plataforma actual (a fecha de hoy, horizon.prefect.io) e inicia sesión con GitHub.

3. Conecta este repositorio.

4. Configura el despliegue:

   • Punto de entrada: mcp_server.py:mcp: la parte :mcp es el nombre de la variable del objeto servidor en el archivo (consulta la línea mcp = FastMCP(...) en mcp_server.py). Si renombras esa variable o mueves el archivo, esta cadena de punto de entrada debe actualizarse para coincidir exactamente.

   • Autenticación: actívala. Los clientes MCP interactivos como claude.ai y Claude Desktop requieren endpoints de descubrimiento OAuth reales para conectarse; un servidor sin autenticación no funcionará con estos clientes, aunque funcione correctamente en pruebas directas con una llamada API simple o el cliente Python de FastMCP.

   • Variables de entorno: añade DATABASE_URL en el panel de control propio de la plataforma. Esto es independiente del archivo .env local del proyecto y no lo lee; el valor debe introducirse directamente en el panel para que el servidor desplegado tenga acceso a la base de datos.

5. Despliega y copia la URL del servidor resultante. Tendrá un aspecto parecido a https://<your-server-name>.fastmcp.app/mcp (el dominio exacto puede variar; usa lo que la plataforma muestre).

6. Antes de conectarlo a otro sitio, pruébalo con el inspector o herramienta de pruebas integrada de la propia plataforma. Llama primero a list_tables allí; no necesita argumentos, por lo que es la manera más rápida de confirmar que el servidor desplegado puede alcanzar la base de datos.

Conexión con claude.ai

1. Ve a claude.ai → Ajustes → Conectores → Añadir conector personalizado.

2. Pega la URL del servidor desplegado del paso de despliegue anterior.

3. Completa el aviso de OAuth que te guíe.

4. Inicia un chat nuevo (no uno que sea anterior a la adición del centro y activa el conector en ese chat.

5. Pruébalo con una pregunta sencilla como «¿qué tablas tengo?».

6. Si más adelante añades herramientas nuevas y no aparecen, prueba Actualizar herramientas en con Border en lugar de asumir que algo se ha roto; es un comportamiento conocido de caché, no un error.

Límites

Es realmente independiente del esquema, pero no está exento de limitaciones:

• Específico de Postgres. Utiliza jsonb_object_keys() y sintaxis de catálogo de Postgres (information_schema, etc.). Apuntando a MySQL o SQLite se necesitarían cambios reales en el código de db_tools.py, no solo una cadena de conexión nueva.

• Independiente del esquema ≠ cero configuración por base de datos. Cada nueva base de datos de destino requiere crear su propio rol de solo lectura (setup_reader_role.sql) y su propio despliegue (o al menos su propio DATABASE_URL) apuntando a ella. Esto no es un único servidor que sirve de forma transparente a varias bases de datos.

Configuración de Git

Si se empieza desde este código sin historial de git todavía:

git init
git add .
git commit -m "Initial commit: generic read-only Postgres MCP server"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main