Servidor MCP PostgreSQL | Awesome MCP Servers

PostgreSQL MCP Server

Um servidor Model Context Protocol (MCP) que fornece capacidades abrangentes de gerenciamento de banco de dados PostgreSQL para assistentes de IA.

🚀 Novidades: Este servidor foi completamente redesenhado de 46 ferramentas individuais para 18 ferramentas inteligentes por meio de consolidação (34→8 meta-ferramentas) e aprimoramento (+4 novas ferramentas), proporcionando melhor descoberta de IA e adicionando poderosas capacidades de manipulação de dados e gerenciamento de comentários.

Mudanças Importantes na 2.0.0

A versão 2.0.0 introduz limites de segurança que alteram intencionalmente o comportamento padrão da linha 1.x:

O servidor inicia no modo readonly. Mutações, DDL, administração de papéis, importação/exportação de sistema de arquivos e SQL arbitrário exigem --security-mode write, --security-mode admin ou --security-mode unsafe conforme apropriado.
Operações destrutivas como drops, resets, concessões amplas de papéis e SQL arbitrário exigem --allow-destructive.
Argumentos connectionString, sourceConnectionString e targetConnectionString por ferramenta estão desabilitados por padrão. Use --connection-string ou POSTGRES_CONNECTION_STRING no nível do servidor, ou opte explicitamente com --allow-tool-connection-string.
Cláusulas where de string legadas são rejeitadas para filtros de mutação, índice, exportação e cópia. Use predicados where estruturados, ou rawWhere apenas com --security-mode unsafe --allow-destructive.
Chamadas pg_execute_sql de múltiplas instruções devem usar transactional: true, expectRows: false e nenhum bind parameters.
Os esquemas de ferramentas rejeitam campos desconhecidos, portanto entradas com erros de digitação ou não intencionais falham antes da resolução da conexão.
Identificadores de usuário e destino são restritos a identificadores PostgreSQL simples e seguros.

Para a linha de patches de segurança sem quebra, use @henkey/postgres-mcp-server@1.0.7.

Início Rápido

Pré-requisitos

Node.js ≥18.0.0
Acesso a um servidor PostgreSQL
(Opcional) Um cliente MCP como Cursor ou Claude para integração com IA

Opção 1: npm (Recomendado)

# Install globally
npm install -g @henkey/postgres-mcp-server

# Or run directly with npx (no installation)
# Use env var for connection string (optional)
export POSTGRES_CONNECTION_STRING="postgresql://user:pass@localhost:5432/db"
npx @henkey/postgres-mcp-server
# Or pass directly:
npx @henkey/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/db"

Verify installation

npx @henkey/postgres-mcp-server --help

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "npx",
      "args": [
        "@henkey/postgres-mcp-server",
        "--connection-string", "postgresql://user:password@host:port/database"
      ]
    }
  }
}

Opção 2: Instalar via Smithery

npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude

Opção 3: Docker (Recomendado para Produção)

# Build the Docker image
docker build -t postgres-mcp-server .

# Run with environment variable
docker run -i --rm \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  postgres-mcp-server

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "henkey/postgres-mcp:latest",
        "-e",
        "POSTGRES_CONNECTION_STRING"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:port/database"
      }
    }
  }
}

Opção 4: Instalação Manual (Desenvolvimento)

git clone <repository-url>
cd postgresql-mcp-server
npm install
npm run build

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "node",
      "args": [
        "/path/to/postgresql-mcp-server/build/index.js",
        "--connection-string", "postgresql://user:password@host:port/database"
      ]
    }
  }
}

Modos de Segurança

O servidor agora inicia no modo readonly por padrão. As ferramentas ainda podem ser listadas para descoberta MCP, mas cada chamada é classificada e verificada antes de chegar ao banco de dados.

Modo	Permite	Bloqueia por padrão
`readonly`	inspeção de esquema, análise, monitoramento, ferramentas de consulta estilo SELECT	mutações, DDL, alterações de papel, importação/exportação de sistema de arquivos, SQL arbitrário
`write`	operações somente leitura mais mutações de dados	DDL, alterações de papel, importação/exportação de sistema de arquivos, SQL arbitrário
`admin`	operações de escrita mais ferramentas de esquema, índice, função, trigger, RLS, papel e sistema de arquivos	SQL arbitrário
`unsafe`	todas as categorias de ferramentas, incluindo SQL arbitrário	operações destrutivas a menos que explicitamente permitidas

Operações destrutivas como drops, resets e SQL arbitrário também exigem aceitação explícita:

# Default: readonly, no per-tool connection strings
npx @henkey/postgres-mcp-server --connection-string "postgresql://readonly_user:pass@host:5432/db"

# Enable DML mutations, but still block DDL/admin/arbitrary SQL
npx @henkey/postgres-mcp-server --security-mode write --connection-string "postgresql://app_writer:pass@host:5432/db"

# Enable admin tools and destructive operations
npx @henkey/postgres-mcp-server --security-mode admin --allow-destructive --connection-string "postgresql://admin_user:pass@host:5432/db"

# Enable arbitrary SQL only for trusted local/admin use
npx @henkey/postgres-mcp-server --security-mode unsafe --allow-destructive --connection-string "postgresql://admin_user:pass@host:5432/db"

Argumentos connectionString, sourceConnectionString e targetConnectionString por ferramenta estão desabilitados por padrão. Prefira uma string de conexão fixa no nível do servidor com um papel PostgreSQL de privilégio mínimo. Apenas para desenvolvimento, habilite strings de conexão por ferramenta com --allow-tool-connection-string ou POSTGRES_MCP_ALLOW_TOOL_CONNECTION_STRING=true. Valores explícitos por ferramenta, CLI e POSTGRES_CONNECTION_STRING devem ser strings não vazias. Strings de conexão em branco com prioridade mais alta falham na validação em vez de recorrer a fontes de prioridade mais baixa.

Opcionalmente, restrinja todas as strings de conexão no nível do servidor e por ferramenta a uma lista de permissões com --allowed-connection-target, allowedConnectionTargets ou POSTGRES_MCP_ALLOWED_CONNECTION_TARGETS. Padrões de destino usam [user@]host[:port][/database]; campos omitidos não têm restrições e * é permitido apenas como curinga de campo completo, por exemplo readonly@db.internal:5432/app ou *@localhost:*/dev.

Para concessões de implantação, consulte PostgreSQL Role Templates. Os modelos dividem credenciais de somente leitura, escritor, administrador de esquema e administrador de papel para que o papel PostgreSQL permaneça alinhado com o securityMode MCP selecionado.

As configurações de segurança também podem ser colocadas no arquivo de configuração de ferramentas:

{
  "securityMode": "readonly",
  "allowDestructive": false,
  "allowToolConnectionString": false,
  "workspaceDir": "/path/to/mcp-workspace",
  "auditFile": "/path/to/postgres-mcp-audit.jsonl",
  "maxConnections": 20,
  "idleTimeoutMillis": 30000,
  "connectionTimeoutMillis": 2000,
  "maxFileBytes": 10485760,
  "statementTimeoutMs": 30000,
  "queryTimeoutMs": 45000,
  "lockTimeoutMs": 10000,
  "idleInTransactionSessionTimeoutMs": 60000,
  "allowedConnectionTargets": [
    "readonly@db.internal:5432/app"
  ],
  "enabledTools": [
    "pg_analyze_database",
    "pg_manage_schema",
    "pg_execute_query"
  ]
}

A precedência de configuração em tempo de execução é: opções de CLI, depois o arquivo de configuração de ferramentas, depois variáveis de ambiente. Valores false explícitos no arquivo de configuração de ferramentas substituem variáveis de ambiente de habilitação como POSTGRES_MCP_ALLOW_DESTRUCTIVE=true.

Se um caminho de configuração de ferramentas for fornecido, o servidor o trata como obrigatório: entradas ilegíveis, malformadas, não-objeto, com tipo incorreto, chave desconhecida, securityMode inválido ou entradas enabledTools desconhecidas interrompem a inicialização em vez de recorrer a todas as ferramentas disponíveis.

Opções de CLI:

--version
--connection-string
--tools-config
--security-mode
--allow-destructive
--allow-tool-connection-string
--workspace-dir
--audit-file
--max-connections
--idle-timeout-ms
--connection-timeout-ms
--max-file-bytes
--statement-timeout-ms
--query-timeout-ms
--lock-timeout-ms
--idle-in-transaction-session-timeout-ms
--allowed-connection-target

Variáveis de ambiente:

POSTGRES_TOOLS_CONFIG=/path/to/tools.json
POSTGRES_MCP_SECURITY_MODE=readonly|write|admin|unsafe
POSTGRES_MCP_ALLOW_DESTRUCTIVE=true
POSTGRES_MCP_ALLOW_TOOL_CONNECTION_STRING=true
POSTGRES_MCP_WORKSPACE_DIR=/path/to/mcp-workspace
POSTGRES_MCP_AUDIT_FILE=/path/to/postgres-mcp-audit.jsonl
POSTGRES_MCP_MAX_CONNECTIONS=20
POSTGRES_MCP_IDLE_TIMEOUT_MS=30000
POSTGRES_MCP_CONNECTION_TIMEOUT_MS=2000
POSTGRES_MCP_MAX_FILE_BYTES=10485760
POSTGRES_MCP_STATEMENT_TIMEOUT_MS=60000
POSTGRES_MCP_QUERY_TIMEOUT_MS=65000
POSTGRES_MCP_LOCK_TIMEOUT_MS=10000
POSTGRES_MCP_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS=60000
POSTGRES_MCP_ALLOWED_CONNECTION_TARGETS=readonly@db.internal:5432/app,*@localhost:*/dev
POSTGRES_MCP_DEBUG_SQL=true para optar pelo rastreamento SQL pg-monitor detalhado. Isso pode registrar SQL bruto e valores de bind, portanto mantenha-o desabilitado a menos que esteja depurando um banco de dados local confiável.

Flags booleanas de ambiente devem ser exatamente true ou false quando definidas. Configurações numéricas de recursos de CLI, configuração de ferramentas ou variáveis de ambiente devem ser inteiros positivos. Os padrões de tempo de execução usam um pool de 20 conexões, um tempo limite de inatividade do pool de 30000 ms, um tempo limite de conexão de 2000 ms, um statement_timeout PostgreSQL de 60000 ms, um tempo limite de consulta node-postgres de 65000 ms, um lock_timeout PostgreSQL de 10000 ms e um idle_in_transaction_session_timeout PostgreSQL de 60000 ms. As configurações de pool e tempo limite podem ser aumentadas ou diminuídas com --max-connections, --idle-timeout-ms, --connection-timeout-ms, --statement-timeout-ms, --query-timeout-ms, --lock-timeout-ms, --idle-in-transaction-session-timeout-ms, maxConnections, idleTimeoutMillis, connectionTimeoutMillis, statementTimeoutMs, queryTimeoutMs, lockTimeoutMs, idleInTransactionSessionTimeoutMs, POSTGRES_MCP_MAX_CONNECTIONS, POSTGRES_MCP_IDLE_TIMEOUT_MS, POSTGRES_MCP_CONNECTION_TIMEOUT_MS, POSTGRES_MCP_STATEMENT_TIMEOUT_MS, POSTGRES_MCP_QUERY_TIMEOUT_MS, POSTGRES_MCP_LOCK_TIMEOUT_MS ou POSTGRES_MCP_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS. Valores explícitos de string de conexão, workspaceDir, auditFile, --workspace-dir e --audit-file devem ser strings não vazias. Listas de permissões de destino de conexão são aplicadas antes da execução da ferramenta para strings de conexão por ferramenta e durante a resolução da conexão para fontes no nível do servidor. Quando uma lista de permissões é configurada, as strings de conexão devem ser URLs PostgreSQL ou strings estilo palavra-chave com um host ou hostaddr explícito.

Filtros de mutação, índice, exportação e cópia devem usar predicados where estruturados. Cláusulas where de string legadas são rejeitadas; a saída de escape rawWhere explícita é tratada como SQL arbitrário e exige --security-mode unsafe --allow-destructive.

Ferramentas EXPLAIN aceitam apenas uma instrução somente leitura e são executadas dentro de uma transação somente leitura. analyze: true ainda exige modo inseguro porque o PostgreSQL executa a consulta fornecida para coletar estatísticas de tempo de execução.

Chamadas pg_execute_sql de múltiplas instruções devem usar transactional: true, expectRows: false e nenhum bind parameters. Use uma única instrução parametrizada ou CTE quando parâmetros de bind forem necessários.

Mensagens de erro, diagnósticos e metadados de catálogo são sanitizados por padrão. Texto SQL de pg_stat_statements, definições de funções, predicados RLS, constraints de verificação, definições de índice e padrões de coluna são ocultados a menos que sejam intencionalmente retornados como dados do usuário. Ferramentas de execução de dados, consulta/desempenho, esquema, índice, constraint, usuário/permissão, trigger, comentário, função, RLS, migração e diagnóstico rejeitam campos de entrada desconhecidos para que parâmetros com erros de digitação ou não intencionais falhem antes da resolução da conexão.

Solicitações negadas por limites de segurança emitem uma linha estruturada em stderr prefixada com [MCP Audit]. Eventos de auditoria incluem campos sanitizados como toolName, reason, securityMode, risk e se strings de conexão por ferramenta estavam presentes; eles não registram SQL bruto, payloads completos de solicitação ou senhas de strings de conexão. Defina POSTGRES_MCP_AUDIT_FILE, --audit-file ou auditFile para anexar os mesmos eventos de auditoria sanitizados a um arquivo JSONL.

Ferramentas de sistema de arquivos como exportação/importação de tabelas exigem um diretório de trabalho e apenas leem ou escrevem arquivos .json e .csv dentro dele:

npx @henkey/postgres-mcp-server \
  --security-mode admin \
  --allow-destructive \
  --workspace-dir /path/to/mcp-workspace \
  --connection-string "postgresql://admin_user:pass@host:5432/db"

O Que Está Incluído

18 ferramentas poderosas organizadas em três categorias:

🔄 Consolidação: 34 ferramentas originais consolidadas em 8 meta-ferramentas inteligentes
🔧 Especializadas: 6 ferramentas mantidas separadas para operações complexas
🆕 Aprimoramento: 4 ferramentas totalmente novas (não estavam nas 46 originais)

📊 Meta-Ferramentas Consolidadas (8 ferramentas)

Gerenciamento de Esquema - Tabelas, colunas, ENUMs, constraints
Usuário e Permissões - Criar usuários, conceder/revogar permissões
Desempenho de Consultas - Planos EXPLAIN, consultas lentas, estatísticas
Gerenciamento de Índices - Criar, analisar, otimizar índices
Funções - Criar, modificar, gerenciar funções armazenadas
Triggers - Gerenciamento de triggers de banco de dados
Constraints - Chaves estrangeiras, verificações, constraints únicas
Segurança em Nível de Linha - Políticas RLS e gerenciamento

🚀 Ferramentas de Aprimoramento (4 NOVAS ferramentas)

Capacidades totalmente novas não disponíveis nas 46 ferramentas originais

Executar Consulta - Operações SELECT com suporte a count/exists
Executar Mutação - Operações INSERT/UPDATE/DELETE/UPSERT
Executar SQL - Execução de SQL arbitrário com suporte a transações
Gerenciamento de Comentários - Gerenciamento abrangente de comentários para todos os objetos do banco de dados

🔧 Ferramentas Especializadas (6 ferramentas)

Análise de Banco de Dados - Análise de desempenho e configuração
Depurar Banco de Dados - Solucionar problemas de conexão, desempenho, locks
Exportação de Dados - Exportação de dados JSON/CSV
Importação de Dados - Importação de dados JSON/CSV
Copiar Entre Bancos de Dados - Transferência de dados entre bancos de dados
Monitoramento em Tempo Real - Métricas e alertas ao vivo do banco de dados

Exemplo de Uso

// Analyze database performance
{ "analysisType": "performance", "schema": "public" }

// Create a table with constraints
{
  "operation": "create_table",
  "tableName": "users", 
  "columns": [
    { "name": "id", "type": "SERIAL PRIMARY KEY" },
    { "name": "email", "type": "VARCHAR(255) UNIQUE NOT NULL" }
  ]
}

// Query data with parameters
{
  "operation": "select",
  "query": "SELECT * FROM users WHERE created_at > $1",
  "parameters": ["2024-01-01"],
  "limit": 100
}
// Select results are always bounded: default limit 100, max 1000.

// Insert new data
{
  "operation": "insert",
  "table": "users",
  "data": {"name": "John Doe", "email": "john@example.com"},
  "returning": "*",
  "maxReturningRows": 100
}
// Mutation RETURNING output is capped in the response: default 100, max 1000.

// Find slow queries
{
  "operation": "get_slow_queries",
  "limit": 5,
  "minDuration": 100
}

// Execute a parameterized SELECT query
{
  "operation": "select",
  "query": "SELECT * FROM users WHERE id = $1",
  "parameters": [1]
}

// Perform an INSERT mutation
{
  "operation": "insert",
  "table": "products",
  "data": {"name": "New Product", "price": 99.99},
  "returning": "id",
  "maxReturningRows": 100
}

// Perform an UPDATE mutation with a structured WHERE predicate
{
  "operation": "update",
  "table": "products",
  "data": {"price": 89.99},
  "where": {"id": 123},
  "returning": ["id", "price"]
}

// Manage database object comments
{
  "operation": "set",
  "objectType": "table",
  "objectName": "users",
  "comment": "Main user account information table"
}

📚 Documentação

📋 Referência Completa de Esquema de Ferramentas - Todos os 18 parâmetros e exemplos de ferramentas em um só lugar

Para informações adicionais, consulte a pasta docs/:

🔐 Postura de Segurança - Sandboxing, aprovações, eventos de auditoria e postura de implantação
PostgreSQL Role Templates - Papéis de banco de dados com privilégio mínimo para cada perfil de implantação
📖 Guia de Uso - Padrões de uso endurecidos e exemplos
🛠️ Guia de Desenvolvimento - Checklist de configuração e lançamento
⚙️ Detalhes Técnicos - Arquitetura de segurança e restrições de implementação
👨‍💻 Referência do Desenvolvedor - Regras de contribuição para alterações de ferramentas e políticas
📋 Índice de Documentação - Visão geral completa da documentação

Destaques de Recursos

🔄 Conquistas da Consolidação

✅ 34→8 meta-ferramentas - Consolidação inteligente para melhor descoberta de IA ✅ Múltiplas operações por ferramenta - Esquemas unificados com parâmetros de operação ✅ Validação inteligente de parâmetros - Mensagens de erro claras e segurança de tipos

🆕 Capacidades de Dados Aprimoradas

✅ Operações CRUD completas - INSERT/UPDATE/DELETE/UPSERT com consultas parametrizadas
✅ Consultas flexíveis - SELECT com suporte a count/exists e limites de segurança delimitados ✅ Execução SQL arbitrária - Suporte a transações para operações complexas

🔧 Pronto para Produção

✅ Conexão controlada - argumentos de CLI ou variáveis de ambiente por padrão; strings de conexão por ferramenta exigem opt-in ✅ Foco em segurança - modo somente leitura por padrão, verificações de política centralizadas, predicados de mutação estruturados ✅ Arquitetura robusta - pool de conexões, tratamento abrangente de erros

Uso com Docker

O PostgreSQL MCP Server é totalmente compatível com Docker e pode ser usado em ambientes de produção. A imagem usa uma construção em múltiplos estágios, instala apenas dependências de produção no estágio de execução e roda como o usuário não-root node.

Construindo a Imagem

# Build locally
docker build -t postgres-mcp-server .

# Or pull from Docker Hub
docker pull henkey/postgres-mcp:latest

Executando com Variáveis de Ambiente

# Basic usage (using Docker Hub image)
docker run -i --rm \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  henkey/postgres-mcp:latest

# Or with locally built image
docker run -i --rm \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  postgres-mcp-server

# With tools configuration
docker run -i --rm \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
  -e POSTGRES_TOOLS_CONFIG="/app/config/tools.json" \
  -v /path/to/config:/app/config \
  postgres-mcp-server

Exemplo de Docker Compose

version: '3.8'
services:
  postgres-mcp:
    build: .
    environment:
      - POSTGRES_CONNECTION_STRING=postgresql://user:password@postgres:5432/database
    depends_on:
      - postgres
    stdin_open: true
    tty: true

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=database
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    ports:
      - "5432:5432"

Configuração do Cliente MCP

Para uso com clientes MCP como Cursor ou Claude Desktop:

{
  "mcpServers": {
    "postgresql-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "POSTGRES_CONNECTION_STRING",
        "henkey/postgres-mcp:latest"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:port/database"
      }
    }
  }
}

Pré-requisitos

Node.js ≥ 18.0.0 (para desenvolvimento local)
Docker (para implantação conteinerizada)
Acesso ao servidor PostgreSQL
Credenciais de conexão válidas

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça commit das suas alterações
Crie um Pull Request

Consulte o Guia de Desenvolvimento para instruções detalhadas de configuração.

Licença

Licença AGPLv3 - consulte o arquivo LICENSE para detalhes.