FastPostgresMCP 🐘⚡️ (Servidor MCP multi-DB con todas las funciones)

Este proyecto implementa un servidor de Protocolo de Contexto de Modelo (MCP) ultrarrápido, seguro en cuanto a tipos y con todas las funciones, diseñado para que los agentes de IA (como Cursor, Claude Desktop) interactúen con múltiples bases de datos PostgreSQL, lo que incluye el listado de tablas y la inspección de esquemas.

Está construido con Bun, TypeScript, postgres y aprovecha las características avanzadas del marco fastmcp para construir servidores MCP robustos.

Propósito: Un servidor MCP para agentes de IA

Esta no es una biblioteca que se pueda importar a su código. Es una aplicación de servidor independiente . Se ejecuta como un proceso y los clientes MCP (como los agentes de IA) se comunican con ella mediante el Protocolo de Contexto de Modelo basado en JSON (v2.0), generalmente a través de una conexión stdio administrada por la aplicación cliente (p. ej., Cursor).

Related MCP server: Postgres MCP Pro

Solución de problemas y desarrollo

Uso de la CLI para realizar pruebas

El paquete incluye un comando CLI integrado para probar el servidor MCP directamente:

# From the project repository:
bun run cli

# This will start an interactive MCP CLI session where you can:
# - Call any of the PostgreSQL tools (query_tool, execute_tool, etc.)
# - View server capabilities
# - Test queries against your configured databases

Pruebas con el inspector MCP integrado

También puede utilizar el Inspector MCP para probar y depurar visualmente:

# From the project repository:
bun run inspect

Problemas comunes

Si ve este error al ejecutar bunx postgres-mcp :

FastPostgresMCP started
[warning] FastMCP could not infer client capabilities

Seguido de mensajes de ping, significa:

1. El servidor MCP se inició correctamente

2. El cliente se conectó exitosamente

3. Pero el cliente solo envía solicitudes de ping y no negocia adecuadamente las capacidades.

Esto suele indicar que necesitas usar un cliente MCP adecuado. Prueba:

• Uso de bun run cli para probar con la CLI de MCP

• Configuración del servidor MCP en Cursor o Claude Desktop como se describe en la sección Instalación

Si está desarrollando un cliente MCP personalizado, asegúrese de que implemente correctamente el protocolo MCP, incluida la negociación de capacidades.

✨ Características principales

• 🚀 Ultrarrápido: Creado con Bun y fastmcp .

• 🔒 Type-Safe: TypeScript de extremo a extremo con validación de esquema Zod.

• 🐘 Compatibilidad con múltiples bases de datos: conéctese y administre interacciones entre varias instancias de PostgreSQL definidas en .env .

• 🛡️ Seguro por diseño: las consultas parametrizadas a través de postgres evitan la inyección de SQL.

• 🔑 Autenticación opcional: conexiones seguras basadas en red (SSE/HTTP) mediante validación de clave API (gancho authenticate de fastmcp ).

• 📄 Esquema de base de datos a través de recursos MCP:

  • Lista de tablas: obtenga una lista de tablas en una base de datos a través de db://{dbAlias}/schema/tables .

  • Inspeccionar esquema de tabla: obtenga información detallada de la columna para una tabla específica a través de db://{dbAlias}/schema/{tableName} .

• 💬 Interacción de herramientas mejorada:

  • Registro en la herramienta: las herramientas envían registros detallados al cliente (contexto log ).

  • Informes de progreso: las operaciones de larga duración informan del progreso (contexto reportProgress ).

• 🧠 Consciente de la sesión: acceder a la información de la sesión dentro del contexto de ejecución de la herramienta (contexto session ).

• 📡 Impulsado por eventos: utiliza server.on y session.on para el manejo de eventos de conexión/sesión.

• 🔧 Experiencia de desarrollador moderna (DX): configuración clara, API intuitiva, pruebas fáciles con herramientas fastmcp .

Qué está incluido (funciones de fastmcp aprovechadas)

• Núcleo del servidor FastMCP

• server.addTool (para query_tool , execute_tool , schema_tool y transaction_tool )

• server.addResourceTemplate (para enumerar tablas e inspeccionar esquemas de tablas)

• server.start (con foco stdio , adaptable para sse / http )

• Opcional: Hook authenticate (para validación de clave API)

• context de ejecución de la herramienta ( log , reportProgress , session )

• Zod para la validación del esquema de parámetros

• server.on (para registro de conexión)

• (Potencialmente) session.on para lógica específica de sesión

📋 Requisitos previos

• Bun (se recomienda v1.0 o posterior): instalado y en PATH.

• Bases de datos PostgreSQL: Credenciales de acceso y conectividad. El usuario necesita permisos para consultar information_schema .

⚙️ Instalación

Opción 1: Paquete NPM

# Install globally
npm install -g postgres-mcp

# Or install locally in your project
npm install postgres-mcp

El paquete npm está disponible en https://www.npmjs.com/package/postgres-mcp

Opción 2: Clonar repositorio

1. Clonar el repositorio:

   # Replace with your actual repository URL
   git clone https://github.com/llm-graph/postgres-mcp.git
   cd postgres-mcp

2. Instalar dependencias:

   bun install

🔑 Configuración (Multi-Base de Datos y Autenticación Opcional)

Configurar a través de variables de entorno, cargadas desde archivos .env apropiados.

1. Crear archivos de entorno:

   • Para producción: cp .env.example .env

   • Para desarrollo: cp .env.development.example .env.development

2. Orden de carga de archivos de entorno: El servidor carga las variables de entorno de los archivos en el siguiente orden de prioridad:

   • .env.<NODE_ENV> (por ejemplo, .env.development , .env.production , .env.staging )

   • .env.local (para anulaciones locales, no controladas por versiones)

   • .env (opción predeterminada) Esto permite diferentes configuraciones para diferentes entornos.

3. Edite los archivos de entorno para definir las conexiones de la base de datos y la autenticación:

   • DB_ALIASES : lista separada por comas de alias de base de datos únicos

   • DEFAULT_DB_ALIAS : alias predeterminado si se omite 'dbAlias' en las llamadas a herramientas

   • Detalles de conexión de base de datos para cada alias (por ejemplo, DB_MAIN_HOST , DB_REPORTING_HOST )

   • Autenticación de clave API opcional ( ENABLE_AUTH , MCP_API_KEY )

# Example .env file - Key Variables

# REQUIRED: Comma-separated list of unique DB aliases
DB_ALIASES=main,reporting

# REQUIRED: Default alias if 'dbAlias' is omitted in tool calls
DEFAULT_DB_ALIAS=main

# OPTIONAL: Enable API Key auth (primarily for network transports)
ENABLE_AUTH=false
MCP_API_KEY=your_super_secret_api_key_here # CHANGE THIS

# Define DB connection details for each alias (DB_MAIN_*, DB_REPORTING_*, etc.)
DB_MAIN_HOST=localhost
DB_MAIN_PORT=5432
DB_MAIN_NAME=app_prod_db
DB_MAIN_USER=app_user
DB_MAIN_PASSWORD=app_secret_password
DB_MAIN_SSL=disable

# Alternative: Use connection URLs
# DB_MAIN_URL=postgres://user:password@localhost:5432/database?sslmode=require

# --- Optional: Server Logging Level ---
# LOG_LEVEL=info # debug, info, warn, error (defaults to info)

🚀 Ejecutar el servidor (como un proceso)

Ejecute este servidor directamente con Bun. El cliente AI (como Cursor) normalmente iniciará y administrará este comando automáticamente.

Opción 1: Usar el paquete instalado globalmente

• Para ejecutar manualmente: postgres-mcp

Opción 2: Usar el paquete en su proyecto

• Para ejecutar desde su proyecto: npx postgres-mcp

• O importar programáticamente:

  // server.js
  import { startServer } from 'postgres-mcp';
  
  // Start the MCP server
  startServer();

Opción 3: Desde el repositorio clonado

• Para ejecutar manualmente (para probar): bun run src/index.ts

• Modo de desarrollo manual: bun run --watch src/index.ts

Pruebas con herramientas CLI fastmcp

• Terminal interactiva: bunx fastmcp dev src/index.ts

• Inspector de interfaz de usuario web: bunx fastmcp inspect src/index.ts

💻 Usando la API programática (como biblioteca)

Además de ejecutarse como un servidor MCP independiente, postgres-mcp también se puede utilizar programáticamente como una biblioteca en sus aplicaciones Node.js/TypeScript.

Uso básico

import { createPostgresMcp } from 'postgres-mcp';

// Create the PostgresMcp instance
const postgresMcp = createPostgresMcp();

// Start the server
postgresMcp.start();

// Direct database operations
const results = await postgresMcp.executeQuery(
  'SELECT * FROM users WHERE role = $1',
  ['admin'],
  'main' // optional database alias
);

// When done, stop the server and close connections
await postgresMcp.stop();

Importaciones de funciones directas

Para casos de uso más simples, puede importar funciones específicas directamente:

import { 
  initConnections, 
  closeConnections, 
  executeQuery, 
  executeCommand, 
  executeTransaction, 
  getTableSchema,
  getAllTableSchemas
} from 'postgres-mcp';

// Configure database connections
const dbConfigs = {
  main: {
    host: 'localhost',
    port: 5432,
    database: 'my_db',
    user: 'db_user',
    password: 'db_password'
  }
};

// Initialize connections
initConnections(dbConfigs);

// Execute a query
const results = await executeQuery(
  'SELECT * FROM users WHERE role = $1',
  ['admin'],
  'main'
);

// Get schema for a single table
const schema = await getTableSchema('users', 'main');

// Get schema for all tables in the database
const allSchemas = await getAllTableSchemas('main');

// Close connections when done
await closeConnections();

Opciones de configuración

const postgresMcp = createPostgresMcp({
  // Custom database configurations (override .env)
  databaseConfigs: {
    main: {
      host: 'localhost',
      port: 5432,
      database: 'app_db',
      user: 'app_user',
      password: 'password',
      ssl: 'disable'
    }
  },
  // Server configuration
  serverConfig: {
    name: 'Custom PostgresMCP',
    defaultDbAlias: 'main'
  },
  // Transport options: 'stdio', 'sse', or 'http'
  transport: 'http',
  port: 3456
});

Para obtener la documentación completa sobre la API programática, consulte docs/programmatic-api.md .

🔌 Conexión con clientes de IA (Cursor, Claude Desktop)

Configure su agente de IA (cliente MCP) para ejecutar este script de servidor a través de su mecanismo de comando/argumentos.

Cursor AI - Ejemplo detallado

1. Abra Configuración/Preferencias del cursor (Cmd+ o Ctrl+).

2. Vaya a "Extensiones" -> "MCP".

3. Haga clic en "Agregar servidor MCP" o edite settings.json .

4. Agregue la siguiente configuración JSON:

   // In Cursor's settings.json or MCP configuration UI
   {
     "mcpServers": {
       "postgres-mcp": { // Unique name for Cursor
         "description": "MCP Server for PostgreSQL DBs (Main, Reporting)",
         "command": "bunx",  // Use 'bun' or provide absolute path: "/Users/your_username/.bun/bin/bun"
         "args": [
           "postgres-mcp"
           // or
           // *** ABSOLUTE PATH to your server's entry point ***
           // "/Users/your_username/projects/postgres-mcp/src/index.ts" /
         ],
         "env": {
           // .env file in project dir is loaded automatically by Bun.
           // Add overrides or Cursor-specific vars here if needed.
         },
         "enabled": true
       }
     }
   }

5. Guardar y reiniciar el cursor o "Recargar servidores MCP".

6. Verificar la conexión en el estado/registros de MCP de Cursor.

Escritorio de Claude

1. Localice y edite config.json (consulte el README anterior para conocer las rutas).

2. Agregue una entrada similar en mcpServers , utilizando la ruta absoluta en args .

3. Reinicie Claude Desktop.

🛠️ Capacidades del MCP expuestas

Autenticación (opcional)

• Protege los transportes de red (HTTP/SSE) a través del encabezado X-API-Key que coincide con MCP_API_KEY si ENABLE_AUTH=true .

• Las conexiones stdio (predeterminadas para Cursor/Claude) generalmente omiten esta verificación.

Recursos

1. Lista de tablas de bases de datos

• Plantilla de URI: db://{dbAlias}/schema/tables

• Descripción: recupera una lista de nombres de tablas de usuario dentro del alias de base de datos especificado (normalmente del esquema 'público').

• Definición de recurso ( addResourceTemplate ):

  • uriTemplate : "db://{dbAlias}/schema/tables"

  • arguments :

    • dbAlias : (cadena, obligatoria) - Alias de la base de datos (desde .env ).

  • load({ dbAlias }) : se conecta a la base de datos, consulta information_schema.tables (filtrado para tablas base en el esquema público, personalizable en la implementación), formatea el resultado como una matriz de cadenas JSON ["table1", "table2", ...] y devuelve { text: "..." } .

Ejemplo de uso (indicador de AI): "Obtenga el recurso db://main/schema/tables para enumerar las tablas en la base de datos principal".

2. Inspeccionar el esquema de la tabla

• Plantilla de URI: db://{dbAlias}/schema/{tableName}

• Descripción: Proporciona información detallada del esquema (columnas, tipos, nulabilidad, valores predeterminados) para una tabla específica.

• Definición de recurso ( addResourceTemplate ):

  • uriTemplate : "db://{dbAlias}/schema/{tableName}"

  • arguments :

    • dbAlias : (cadena, obligatoria) - Alias de la base de datos.

    • tableName : (cadena, obligatoria) - Nombre de la tabla.

  • load({ dbAlias, tableName }) : se conecta, consulta information_schema.columns para la tabla específica, formatea como una matriz de cadenas JSON de objetos de columna, devuelve { text: "..." } .

Ejemplo de uso (indicador de IA): "Describe el recurso db://reporting/schema/daily_sales ".

Ejemplo de contenido de respuesta (cadena JSON):

"[{\"column_name\":\"session_id\",\"data_type\":\"uuid\",\"is_nullable\":\"NO\",\"column_default\":\"gen_random_uuid()\"},{\"column_name\":\"user_id\",\"data_type\":\"integer\",\"is_nullable\":\"NO\",\"column_default\":null},{\"column_name\":\"created_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":\"now()\"},{\"column_name\":\"expires_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":null}]"

Herramientas

Las herramientas reciben un objeto context ( log , reportProgress , session ).

1. query_tool

Ejecuta consultas SQL de solo lectura.

• Descripción: Ejecute de forma segura SQL de solo lectura, obtenga resultados, con registro/progreso de ejecución.

• Parámetros: statement (cadena), params (matriz, opción), dbAlias (cadena, opción).

• Uso de contexto: log.info/debug , reportProgress opcional , session de acceso.

• Devuelve: cadena JSON de la matriz de filas.

Ejemplo de solicitud:

{
  "tool_name": "query_tool",
  "arguments": {
    "statement": "SELECT product_id, name, price FROM products WHERE category = $1 AND price < $2 ORDER BY name LIMIT 10",
    "params": ["electronics", 500],
    "dbAlias": "main"
  }
}

Ejemplo de contenido de respuesta (cadena JSON):

"[{\"product_id\":123,\"name\":\"Example Gadget\",\"price\":499.99},{\"product_id\":456,\"name\":\"Another Device\",\"price\":350.00}]"

2. execute_tool

Ejecuta sentencias SQL que modifican datos.

• Descripción: Ejecute SQL que modifique datos de forma segura, con registro de ejecución.

• Parámetros: statement (cadena), params (matriz, opción), dbAlias (cadena, opción).

• Uso de contexto: log.info/debug , acceso session .

• Devuelve: Cadena que indica las filas afectadas.

Ejemplo de solicitud:

{
  "tool_name": "execute_tool",
  "arguments": {
    "statement": "UPDATE users SET last_login = NOW() WHERE user_id = $1",
    "params": [54321]
    // dbAlias omitted, uses DEFAULT_DB_ALIAS
  }
}

Ejemplo de contenido de respuesta (cadena):

"Rows affected: 1"

3. schema_tool

Recupera información detallada del esquema para una tabla específica.

• Descripción: Obtenga definiciones de columnas y detalles para una tabla de base de datos.

• Parámetros: tableName (cadena), dbAlias (cadena, opt).

• Uso de contexto: log.info , session de acceso .

• Devuelve: matriz de cadenas JSON de objetos de información de columnas.

Ejemplo de solicitud:

{
  "tool_name": "schema_tool",
  "arguments": {
    "tableName": "user_sessions",
    "dbAlias": "main"
  }
}

Ejemplo de contenido de respuesta (cadena JSON):

"[{\"column_name\":\"session_id\",\"data_type\":\"uuid\",\"is_nullable\":\"NO\",\"column_default\":\"gen_random_uuid()\"},{\"column_name\":\"user_id\",\"data_type\":\"integer\",\"is_nullable\":\"NO\",\"column_default\":null},{\"column_name\":\"created_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":\"now()\"},{\"column_name\":\"expires_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":null}]"

4. transaction_tool

Ejecuta múltiples sentencias SQL de forma atómica.

• Descripción: Ejecutar secuencia SQL en una transacción, con registro/progreso de pasos.

• Parámetros: operations (matriz de {declaración, parámetros}), dbAlias (cadena, opción).

• Uso de contexto: log.info/debug/error , reportProgress , access session .

• Devuelve: cadena JSON que resume el éxito/fracaso: {"success": true, "results": [...]} o {"success": false, "error": ..., "failedOperationIndex": ...} .

Ejemplo de solicitud:

{
  "tool_name": "transaction_tool",
  "arguments": {
    "operations": [
      {
        "statement": "INSERT INTO orders (customer_id, order_date, status) VALUES ($1, NOW(), 'pending') RETURNING order_id",
        "params": [101]
      },
      {
        "statement": "INSERT INTO order_items (order_id, product_sku, quantity, price) VALUES ($1, $2, $3, $4)",
        "params": [9999, "GADGET-X", 2, 49.99]
      },
      {
        "statement": "UPDATE inventory SET stock_count = stock_count - $1 WHERE product_sku = $2 AND stock_count >= $1",
        "params": [2, "GADGET-X"]
      }
    ],
    "dbAlias": "main"
  }
}

Ejemplo de contenido de respuesta de éxito (cadena JSON):

"{\"success\":true,\"results\":[{\"operation\":0,\"rowsAffected\":1},{\"operation\":1,\"rowsAffected\":1},{\"operation\":2,\"rowsAffected\":1}]}"

Ejemplo de contenido de respuesta de error (cadena JSON):

"{\"success\":false,\"error\":\"Error executing operation 2: new row for relation \\\"inventory\\\" violates check constraint \\\"stock_count_non_negative\\\"\",\"failedOperationIndex\":2}"

Eventos de servidor y sesión

• Utiliza server.on('connect'/'disconnect') para registrar las conexiones del cliente.

• Se puede utilizar session.on(...) para un manejo más granular de eventos de sesión si es necesario.

Consideraciones de seguridad

• Inyección SQL: Mitigada mediante consultas parametrizadas. Sin concatenación directa de entradas.

• Permisos de base de datos: Críticos. Asignar el mínimo privilegio a cada DB_<ALIAS>_USER , incluyendo acceso de lectura a information_schema para recursos de listado de esquemas/tablas.

• SSL/TLS: Esencial para producción ( DB_<ALIAS>_SSL=require o más estricto).

• Gestión de secretos: Proteja el archivo .env (añádalo a .gitignore ). Utilice la gestión segura de secretos para entornos de producción (Vault, Doppler, secretos en la nube).

• Alcance de autenticación: el gancho authenticate protege principalmente los transportes de red. La seguridad stdio depende del entorno de ejecución.

• Sensibilidad de los datos: tenga en cuenta los datos a los que se puede acceder a través de conexiones/herramientas.

• Consultas de recursos: Las consultas utilizadas para listar tablas ( information_schema.tables ) y esquemas ( information_schema.columns ) suelen ser seguras, pero dependen de los permisos de la base de datos. Asegúrese de que los usuarios configurados tengan el acceso de lectura adecuado. Personalice la consulta de lista de tablas (p. ej., filtrado de esquemas) si es necesario para mayor seguridad o claridad.

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT . Consulte el archivo de LICENCIA para más detalles.

📋 Registro de cambios

1.0.0

• Lanzamiento inicial

• Servidor MCP con todas las funciones para PostgreSQL

• Soporte para múltiples conexiones de bases de datos

• Herramientas para consultas, ejecución, inspección de esquemas y transacciones

• Recursos para la introspección de esquemas

• Documentación completa y ejemplos