MCP PostgreSQL Server

Un servidor MCP (Model Context Protocol) para PostgreSQL que permite a Cursor y otras herramientas interactuar con bases de datos PostgreSQL a través de HTTP.

Características

• ✅ Protocolo MCP completo implementado
• ✅ Conexión a PostgreSQL
• ✅ Servidor HTTP con Express
• ✅ Endpoints REST para pruebas directas
• ✅ Herramientas MCP para consultas SQL
• ✅ Soporte para esquemas y metadatos
• ✅ Manejo de errores robusto

Instalación

1. Clona o descarga este proyecto.
2. Instala las dependencias:

npm install

3. Copia el archivo de configuración:

cp .env.example .env

4. Configura las variables de entorno en .env:

PORT=3000
DB_HOST=localhost
DB_PORT=5432
DB_NAME=tu_base_de_datos
DB_USER=tu_usuario
DB_PASSWORD=tu_contraseña
DB_SSL=false

Uso

Iniciar el servidor

# Modo desarrollo (con auto-reload)
npm run dev

# Modo producción
npm start

El servidor estará disponible en http://localhost:3000

Endpoints disponibles

Health Check

GET /health

MCP Protocol

POST /mcp

Endpoint principal para comunicación MCP.

Consulta directa

POST /query
Content-Type: application/json

{
  "query": "SELECT * FROM users LIMIT 10",
  "params": []
}

Listar tablas

GET /tables

Describir tabla

GET /tables/:tableName

Configuración en Cursor

Para usar este servidor MCP en Cursor, agrega la siguiente configuración:

Configuración MCP en Cursor

Crea o edita el archivo de configuración de Cursor (ubicación depende del OS):

macOS: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/config.json Windows: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\config.json Linux: ~/.config/Cursor/User/globalStorage/cursor.mcp/config.json

{
  "mcpServers": {
    "postgres": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

También se incluye un archivo cursor-mcp-config.json en el proyecto como ejemplo de configuración.

Herramientas MCP disponibles

postgres_query

Ejecuta consultas SQL en la base de datos.

{
  "name": "postgres_query",
  "arguments": {
    "query": "SELECT * FROM users WHERE id = $1",
    "params": ["123"]
  }
}

postgres_tables

Lista todas las tablas en la base de datos.

{
  "name": "postgres_tables",
  "arguments": {}
}

postgres_schema

Obtiene información del esquema de la base de datos.

{
  "name": "postgres_schema",
  "arguments": {
    "table_name": "users"
  }
}

postgres_describe_table

Describe la estructura de una tabla específica.

{
  "name": "postgres_describe_table",
  "arguments": {
    "table_name": "users"
  }
}

Ejemplos de uso

Consulta simple

curl -X POST http://localhost:3000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT version()"}'

Consulta con parámetros

curl -X POST http://localhost:3000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM users WHERE age > $1", "params": ["25"]}'

Solicitud MCP

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "postgres_tables",
      "arguments": {}
    }
  }'

Desarrollo

Estructura del proyecto

src/
├── server.js          # Servidor HTTP principal
├── mcp-protocol.js    # Implementación del protocolo MCP
└── database.js        # Conexión y utilidades de PostgreSQL

test/
└── test.js           # Tests básicos

.env.example          # Ejemplo de variables de entorno
package.json          # Dependencias y scripts
README.md            # Este archivo

Agregar nuevas herramientas

1. Edita src/mcp-protocol.js
2. Registra la nueva herramienta en initialize()
3. Implementa el manejador en handleToolCall()

Requisitos

• Node.js 18+
• PostgreSQL 12+
• npm o yarn

Solución de problemas

Error de conexión a la base de datos

• Verifica que PostgreSQL esté ejecutándose
• Comprueba las credenciales en .env
• Asegúrate de que la base de datos existe

Puerto en uso

• Cambia el puerto en .env con PORT=otro_puerto

Permisos insuficientes

• Verifica que el usuario de la base de datos tenga permisos de lectura/escritura

Contribuir

1. Fork del proyecto
2. Crea una rama para tu feature
3. Commit tus cambios
4. Push a la rama
5. Abre un Pull Request

Licencia

MIT