Servidor MCP Postgres | Awesome MCP Servers

PGMCP - Servidor de Protocolo de Contexto de Modelo PostgreSQL

O PGMCP conecta assistentes de IA a qualquer banco de dados PostgreSQL por meio de consultas em linguagem natural. Faça perguntas em inglês simples e obtenha resultados SQL estruturados com streaming automático e tratamento robusto de erros.

Funciona com: Cursor, Claude Desktop, extensões do VS Code e qualquer cliente compatível com MCP

Início Rápido

O PGMCP conecta-se ao seu banco de dados PostgreSQL existente e o torna acessível a assistentes de IA por meio de consultas em linguagem natural.

Pré-requisitos

Banco de dados PostgreSQL (banco de dados existente com seu esquema)
Chave da API OpenAI (opcional, para geração de SQL com 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

Veja 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

Recursos

Linguagem Natural para SQL: Faça perguntas em inglês simples
Streaming Automático: Lida com grandes conjuntos de resultados automaticamente
Acesso Somente Leitura Seguro: Impede qualquer operação de escrita
Pesquisa de Texto: Pesquise em todas as colunas de texto
Múltiplos Formatos de Saída: Tabela, JSON e CSV
Sensibilidade a Maiúsculas do PostgreSQL: Lida corretamente com nomes de tabelas com maiúsculas e minúsculas
Compatibilidade Universal: Funciona com qualquer banco de dados PostgreSQL

Variáveis de Ambiente

Obrigatórias:

DATABASE_URL: string de conexão PostgreSQL para seu banco de dados existente

Opcionais:

OPENAI_API_KEY: chave da API OpenAI para geração de SQL com IA
OPENAI_MODEL: modelo a usar (padrão: "gpt-4o-mini")
HTTP_ADDR: endereço do servidor (padrão: ":8080")
HTTP_PATH: caminho do endpoint MCP (padrão: "/mcp")
AUTH_BEARER: token Bearer para autenticação

Instalação

Baixar Binários Pré-compilados

Vá para GitHub Releases
Baixe o binário para sua plataforma (Linux, macOS, Windows)
Extraia e execute:

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

Opções 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

Adicione -ldflags="-s -w -extldflags=-static" -trimpath se quiser obter executáveis reduzidos (sem informações de depuração):

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/

Início 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

Variáveis de Ambiente

Obrigatórias:

DATABASE_URL: string de conexão PostgreSQL

Opcionais:

OPENAI_API_KEY: chave da API OpenAI para geração de SQL
OPENAI_MODEL: modelo a usar (padrão: "gpt-4o-mini")
HTTP_ADDR: endereço do servidor (padrão: ":8080")
HTTP_PATH: caminho do endpoint MCP (padrão: "/mcp")
AUTH_BEARER: token Bearer para autenticação

Exemplos 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

Banco de Dados de Exemplo

O projeto inclui dois esquemas:

schema.sql: marketplace completo semelhante à Amazon com mais de 5.000 registros
schema_minimal.sql: esquema de teste mínimo com tabela "Categories" com maiúsculas e minúsculas

Principais recursos:

Nomes de tabelas com maiúsculas e minúsculas ("Categories") para testar a sensibilidade a maiúsculas
Chaves primárias compostas (order_items) para testar suposições da IA
Relacionamentos realistas e tipos de dados

Use seu próprio banco de dados:

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

Tratamento de Erros de IA

Quando a IA gera SQL incorreto, o PGMCP lida com isso de forma elegante:

{
  "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..."
}

Em vez de travar, o sistema fornece feedback útil e continua operando.

Integração MCP

Integração com Cursor

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

Adicione às configurações do Cursor:

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

Integração com Claude Desktop

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

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

Ferramentas de API

ask: perguntas em linguagem natural → consultas SQL com streaming automático
search: pesquisa de texto livre em todas as colunas de texto do banco de dados
stream: streaming avançado para conjuntos de resultados muito grandes com paginação

Recursos de Segurança

Imposição de Somente Leitura: bloqueia operações de escrita (INSERT, UPDATE, DELETE, etc.)
Tempos Limite de Consulta: impede consultas de longa duração
Validação de Entrada: sanitiza e valida toda a entrada do usuário
Isolamento de Transação: todas as consultas são executadas em transações somente leitura

Testes

# Unit tests
go test ./server -v

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

Licença

Apache 2.0 - Consulte o arquivo LICENSE para obter detalhes.

Projetos Relacionados

Model Context Protocol - A especificação do protocolo subjacente
MCP Go SDK - Implementação Go do MCP

O PGMCP torna seu banco de dados PostgreSQL acessível a assistentes de IA por meio de linguagem natural, mantendo a segurança por meio de controles de acesso somente leitura.

Postgres MCP

Documentação

PGMCP - Servidor de Protocolo de Contexto de Modelo PostgreSQL

Início Rápido

Pré-requisitos

Uso Básico

Recursos

Variáveis de Ambiente

Instalação

Baixar Binários Pré-compilados

Opções Alternativas

Docker/Kubernetes

Início Rápido

Variáveis de Ambiente

Exemplos de Uso

Banco de Dados de Exemplo

Tratamento de Erros de IA

Integração MCP

Integração com Cursor

Integração com Claude Desktop

Ferramentas de API

Recursos de Segurança

Testes

Licença

Projetos Relacionados