Servidor MCP de Postgres | Awesome MCP Servers

PGMCP - Servidor de Protocolo de Contexto de Modelo PostgreSQL

PGMCP conecta asistentes de IA a cualquier base de datos PostgreSQL mediante consultas en lenguaje natural. Haz preguntas en inglés sencillo y obtén resultados SQL estructurados con transmisión automática y manejo robusto de errores.

Funciona con: Cursor, Claude Desktop, extensiones de VS Code y cualquier cliente compatible con MCP

Inicio Rápido

PGMCP se conecta a tu base de datos PostgreSQL existente y la hace accesible a asistentes de IA mediante consultas en lenguaje natural.

Requisitos Previos

Base de datos PostgreSQL (base de datos existente con tu esquema)
Clave de API de OpenAI (opcional, para generación de SQL impulsada por IA)

Uso Básico

# Set up environment variables
export DATABASE_URL="postgres://user:password@localhost:5432/your-existing-db"
export OPENAI_API_KEY="your-api-key"  # Optional

# Run server (using pre-compiled binary)
./pgmcp-server

# Test with client in another terminal
./pgmcp-client -ask "What tables do I have?" -format table
./pgmcp-client -ask "Who is the customer that has placed the most orders?" -format table
./pgmcp-client -search "john" -format table

Así es como funciona:

👤 User / AI Assistant
         │
         │ "Who are the top customers?"
         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Any MCP Client                           │
│                                                             │
│  PGMCP CLI  │  Cursor  │  Claude Desktop  │  VS Code  │ ... │
│  JSON/CSV   │  Chat    │  AI Assistant    │  Editor   │     │
└─────────────────────────────────────────────────────────────┘
         │
         │ Streamable HTTP / MCP Protocol
         ▼
┌─────────────────────────────────────────────────────────────┐
│                    PGMCP Server                             │
│                                                             │
│  🔒 Security    🧠 AI Engine      🌊 Streaming              │
│  • Input Valid  • Schema Cache    • Auto-Pagination         │
│  • Audit Log    • OpenAI API      • Memory Management       │
│  • SQL Guard    • Error Recovery  • Connection Pool         │
└─────────────────────────────────────────────────────────────┘
         │
         │ Read-Only SQL Queries
         ▼
┌─────────────────────────────────────────────────────────────┐
│                Your PostgreSQL Database                     │
│                                                             │
│  Any Schema: E-commerce, Analytics, CRM, etc.               │
│  Tables • Views • Indexes • Functions                       │
└─────────────────────────────────────────────────────────────┘

External AI Services:
OpenAI API • Anthropic • Local LLMs (Ollama, etc.)

Key Benefits:
✅ Works with ANY PostgreSQL database (no assumptions about schema)
✅ No schema modifications required  
✅ Read-only access (100% safe)
✅ Automatic streaming for large results
✅ Intelligent query understanding (singular vs plural)
✅ Robust error handling (graceful AI failure recovery)
✅ PostgreSQL case sensitivity support (mixed-case tables)
✅ Production-ready security and performance
✅ Universal database compatibility
✅ Multiple output formats (table, JSON, CSV)
✅ Free-text search across all columns
✅ Authentication support
✅ Comprehensive testing suite

Características

Lenguaje natural a SQL: Haz preguntas en inglés sencillo
Transmisión automática: Maneja conjuntos de resultados grandes automáticamente
Acceso seguro de solo lectura: Evita cualquier operación de escritura
Búsqueda de texto: Busca en todas las columnas de texto
Múltiples formatos de salida: Tabla, JSON y CSV
Sensibilidad a mayúsculas de PostgreSQL: Maneja correctamente nombres de tablas con mayúsculas y minúsculas
Compatibilidad universal: Funciona con cualquier base de datos PostgreSQL

Variables de Entorno

Requeridas:

DATABASE_URL: Cadena de conexión de PostgreSQL a tu base de datos existente

Opcionales:

OPENAI_API_KEY: Clave de API de OpenAI para generación de SQL impulsada por IA
OPENAI_MODEL: Modelo a usar (por defecto: "gpt-4o-mini")
HTTP_ADDR: Dirección del servidor (por defecto: ":8080")
HTTP_PATH: Ruta del endpoint de MCP (por defecto: "/mcp")
AUTH_BEARER: Token Bearer para autenticación

Instalación

Descargar Binarios Precompilados

Ve a GitHub Releases
Descarga el binario para tu plataforma (Linux, macOS, Windows)
Extrae y ejecuta:

# Example for macOS/Linux
tar xzf pgmcp_*.tar.gz
cd pgmcp_*
./pgmcp-server

Opciones Alternativas

# Homebrew (macOS/Linux) - Available after first release
brew tap subnetmarco/homebrew-tap
brew install pgmcp

# Build from source
go build -o pgmcp-server ./server
go build -o pgmcp-client ./client

Agrega -ldflags="-s -w -extldflags=-static" -trimpath si deseas obtener ejecutables reducidos (sin información de depuración):

go build -ldflags="-s -w -extldflags=-static" -trimpath -o pgmcp-server ./server
go build -ldflags="-s -w -extldflags=-static" -trimpath -o pgmcp-client ./client

Docker/Kubernetes

# Docker
docker run -e DATABASE_URL="postgres://user:pass@host:5432/db" \
  -p 8080:8080 ghcr.io/subnetmarco/pgmcp:latest

# Kubernetes (see examples/ directory for full manifests)
kubectl create secret generic pgmcp-secret \
  --from-literal=database-url="postgres://user:pass@host:5432/db"
kubectl apply -f examples/k8s/

Inicio Rápido

# Set up database (optional - works with any existing PostgreSQL database)
export DATABASE_URL="postgres://user:password@localhost:5432/mydb"
psql $DATABASE_URL < schema.sql

# Run server
export OPENAI_API_KEY="your-api-key"
./pgmcp-server

# Test with client
./pgmcp-client -ask "Who is the user that places the most orders?" -format table
./pgmcp-client -ask "Show me the top 40 most reviewed items in the marketplace" -format table

Variables de Entorno

Requeridas:

DATABASE_URL: Cadena de conexión de PostgreSQL

Opcionales:

OPENAI_API_KEY: Clave de API de OpenAI para generación de SQL
OPENAI_MODEL: Modelo a usar (por defecto: "gpt-4o-mini")
HTTP_ADDR: Dirección del servidor (por defecto: ":8080")
HTTP_PATH: Ruta del endpoint de MCP (por defecto: "/mcp")
AUTH_BEARER: Token Bearer para autenticación

Ejemplos de Uso

# Ask questions in natural language
./pgmcp-client -ask "What are the top 5 customers?" -format table
./pgmcp-client -ask "How many orders were placed today?" -format json

# Search across all text fields
./pgmcp-client -search "john" -format table

# Multiple questions at once
./pgmcp-client -ask "Show tables" -ask "Count users" -format table

# Different output formats
./pgmcp-client -ask "Export all data" -format csv -max-rows 1000

Base de Datos de Ejemplo

El proyecto incluye dos esquemas:

schema.sql: Mercado completo similar a Amazon con más de 5,000 registros
schema_minimal.sql: Esquema de prueba mínimo con tabla "Categories" de mayúsculas y minúsculas mixtas

Características clave:

Nombres de tablas con mayúsculas y minúsculas ("Categories") para probar la sensibilidad a mayúsculas
Claves primarias compuestas (order_items) para probar suposiciones de IA
Relaciones realistas y tipos de datos

Usa tu propia base de datos:

export DATABASE_URL="postgres://user:pass@host:5432/your_db"
./pgmcp-server
./pgmcp-client -ask "What tables do I have?"

Manejo de Errores de IA

Cuando la IA genera SQL incorrecto, PGMCP lo maneja con elegancia:

{
  "error": "Column not found in generated query",
  "suggestion": "Try rephrasing your question or ask about specific tables",
  "original_sql": "SELECT non_existent_column FROM table..."
}

En lugar de fallar, el sistema proporciona comentarios útiles y continúa operando.

Integración MCP

Integración con Cursor

# Start server
export DATABASE_URL="postgres://user:pass@localhost:5432/your_db"
./pgmcp-server

Agrega a la configuración de Cursor:

{
  "mcp.servers": {
    "pgmcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8080/mcp"
      }
    }
  }
}

Integración con Claude Desktop

Edita ~/.config/claude-desktop/claude_desktop_config.json:

{
  "mcpServers": {
    "pgmcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8080/mcp"
      }
    }
  }
}

Herramientas de API

ask: Preguntas en lenguaje natural → consultas SQL con transmisión automática
search: Búsqueda de texto libre en todas las columnas de texto de la base de datos
stream: Transmisión avanzada para conjuntos de resultados muy grandes con paginación

Características de Seguridad

Aplicación de solo lectura: Bloquea operaciones de escritura (INSERT, UPDATE, DELETE, etc.)
Tiempos de espera de consulta: Evita consultas de larga duración
Validación de entrada: Sanea y valida toda la entrada del usuario
Aislamiento de transacciones: Todas las consultas se ejecutan en transacciones de solo lectura

Pruebas

# Unit tests
go test ./server -v

# Integration tests (requires PostgreSQL)
go test ./server -tags=integration -v

Licencia

Apache 2.0 - Consulta el archivo LICENSE para más detalles.

Proyectos Relacionados

Model Context Protocol - La especificación del protocolo subyacente
MCP Go SDK - Implementación de MCP en Go

PGMCP hace que tu base de datos PostgreSQL sea accesible para asistentes de IA mediante lenguaje natural, manteniendo la seguridad a través de controles de acceso de solo lectura.

Postgres MCP

Documentación

PGMCP - Servidor de Protocolo de Contexto de Modelo PostgreSQL

Inicio Rápido

Requisitos Previos

Uso Básico

Características

Variables de Entorno

Instalación

Descargar Binarios Precompilados

Opciones Alternativas

Docker/Kubernetes

Inicio Rápido

Variables de Entorno

Ejemplos de Uso

Base de Datos de Ejemplo

Manejo de Errores de IA

Integración MCP

Integración con Cursor

Integración con Claude Desktop

Herramientas de API

Características de Seguridad

Pruebas

Licencia

Proyectos Relacionados