MCP-PostgreSQL-Ops

MCP-PostgreSQL-Ops é um servidor MCP profissional para operações, monitoramento e gerenciamento de banco de dados PostgreSQL. Suporta PostgreSQL 12-17 com análise abrangente de banco de dados, monitoramento de desempenho e recomendações inteligentes de manutenção por meio de consultas em linguagem natural.

GitHub
160
Experimente este MCPPatrocinado

Documentação

Servidor MCP para Operações e Monitoramento de PostgreSQL

MCP Toplist

License: MIT Python Docker Pulls PostgreSQL BuyMeACoffee

Deploy to PyPI with tag PyPI PyPI - Downloads

Arquitetura e Internos (DeepWiki)

Ask DeepWiki

Visão Geral

MCP-PostgreSQL-Ops é um servidor MCP profissional para operações, monitoramento e gerenciamento de banco de dados PostgreSQL. Suporta PostgreSQL 12-18 com análise abrangente de banco de dados, monitoramento de desempenho e recomendações inteligentes de manutenção por meio de consultas em linguagem natural. A maioria dos recursos funciona de forma independente, mas os recursos avançados de análise de consultas são aprimorados quando as extensões pg_stat_statements e (opcionalmente) pg_stat_monitor estão instaladas.

Recursos

  • ✅ Zero Configuração: Funciona com PostgreSQL 12-18 pronto para uso, com detecção automática de versão.
  • ✅ Linguagem Natural: Faça perguntas como "Mostre-me consultas lentas" ou "Analise o inchaço da tabela."
  • ✅ Seguro para Produção: Operações somente leitura, compatível com RDS/Aurora com permissões de usuário regulares.
  • ✅ Aprimorado por Extensões: pg_stat_statements e pg_stat_monitor opcionais para análises avançadas de consultas.
  • ✅ Monitoramento Abrangente de Banco de Dados: Análise de desempenho, detecção de inchaço e recomendações de manutenção.
  • ✅ Análise Inteligente de Consultas: Identificação de consultas lentas com integração pg_stat_statements e pg_stat_monitor.
  • ✅ Descoberta de Esquema e Relacionamentos: Exploração da estrutura do banco de dados com mapeamento detalhado de relacionamentos.
  • ✅ Inteligência de VACUUM e Autovacuum: Monitoramento de manutenção em tempo real e análise de eficácia.
  • ✅ Operações Multi-Banco de Dados: Análise e monitoramento contínuos entre bancos de dados.
  • ✅ Pronto para Empresas: Operações seguras somente leitura com compatibilidade com RDS/Aurora.
  • ✅ Amigável para Desenvolvedores: Base de código simples para fácil personalização e extensão de ferramentas.

🔧 Recursos Avançados

  • Estatísticas de I/O cientes da versão (aprimoradas no PostgreSQL 16+, colunas de bytes no PG 18+).
  • Monitoramento de conexões e bloqueios em tempo real.
  • Análise de processos em segundo plano e checkpoints.
  • Status de replicação e monitoramento de WAL.
  • Análise de capacidade e inchaço do banco de dados.
  • Catálogo de eventos de espera com descrições (PG 17+).
  • Monitoramento do resumidor de WAL para backups incrementais (PG 17+).
  • Monitoramento do subsistema de I/O assíncrono (PG 18+).
  • Estatísticas de I/O e WAL por backend (PG 18+).

Exemplos de Uso de Ferramentas

📸 Mais Exemplos com Capturas de Tela →

MCP-PostgreSQL-Ops Usage Screenshot

MCP-PostgreSQL-Ops Usage Screenshot

⭐ Início Rápido (5 minutos)

Nota: O contêiner postgresql incluído em docker-compose.yml destina-se apenas a fins de teste de início rápido. Você pode se conectar à sua própria instância do PostgreSQL ajustando as variáveis de ambiente conforme necessário.

Se você quiser usar sua própria instância do PostgreSQL em vez do contêiner de teste integrado:

  • Atualize as informações de conexão do PostgreSQL de destino no seu arquivo .env (consulte POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB).
  • Em docker-compose.yml, comente (desative) os contêineres postgres e postgres-init-extensions para evitar iniciar o banco de dados de teste integrado.

Diagrama de Fluxo do Início Rápido/Tutorial

Flow Diagram of Quickstart/Tutorial

1. Configuração do Ambiente

Nota: Embora os privilégios de superusuário forneçam acesso a todos os bancos de dados e informações do sistema, o servidor MCP também funciona com permissões de usuário regulares para tarefas básicas de monitoramento.

git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

### Check and modify .env file
cp .env.example .env
vim .env

### No need to modify defaults, but if using your own PostgreSQL server, edit below:
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=15432  # External port for host access (mapped to internal 5432)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme!@34
POSTGRES_DB=ecommerce # Default connection DB. Superusers can access all DBs.

Nota: PGDATA=/data/db está pré-configurado para a imagem Docker do Percona PostgreSQL, que requer esse caminho específico para permissões de gravação adequadas.

2. Iniciar Contêineres de Demonstração

# Start all containers including built-in PostgreSQL for testing
docker-compose up -d

# Alternative: If using your own PostgreSQL instance
# Comment out postgres and postgres-init-extensions services in docker-compose.yml
# Then use the custom configuration:
# docker-compose -f docker-compose.custom-db.yml up -d

⏰ Aguarde a Configuração do Ambiente: A configuração inicial do ambiente leva alguns minutos, pois os contêineres são iniciados em sequência:

  1. O contêiner PostgreSQL inicia primeiro com a inicialização do banco de dados
  2. O contêiner PostgreSQL Extensions instala extensões e cria dados de teste abrangentes (~83 mil registros)
  3. Os contêineres MCP Server e MCPO Proxy iniciam depois que o PostgreSQL está pronto
  4. O contêiner OpenWebUI inicia por último e pode levar mais tempo para carregar a interface web

💡 Dica: Aguarde 2-3 minutos após executar docker-compose up -d antes de acessar o OpenWebUI para garantir que todos os serviços estejam totalmente inicializados.

🔍 Verificar o Status do Contêiner (Opcional):

# Monitor container startup progress
docker-compose logs -f

# Check if all containers are running
docker-compose ps

# Verify PostgreSQL is ready
docker-compose logs postgres | grep "ready to accept connections"

3. Acesso ao OpenWebUI

http://localhost:3003/

  • A lista de recursos de ferramentas MCP fornecidos por swagger pode ser encontrada no URL da Documentação da API do MCPO.
    • ex: http://localhost:8003/docs

4. Registrando a Ferramenta no OpenWebUI

📌 Nota: As instruções de configuração da Web-UI são baseadas no OpenWebUI v0.6.22. Os locais de menu e as configurações podem diferir em versões mais recentes.

  1. Faça login no OpenWebUI com uma conta de administrador
  2. Vá para "Configurações" → "Ferramentas" no menu superior.
  3. Digite o endereço da Ferramenta postgresql-ops (ex: http://localhost:8003/postgresql-ops) para conectar as Ferramentas MCP.
  4. Configure o Ollama ou OpenAI.

5. Concluído!

Parabéns! Seu servidor MCP PostgreSQL Operations está pronto para uso. Você pode começar a explorar seus bancos de dados com consultas em linguagem natural.

🚀 Experimente Estas Consultas de Exemplo:

  • "Mostre-me as conexões ativas atuais"
  • "Quais são as consultas mais lentas do sistema?"
  • "Analise o inchaço da tabela em todos os bancos de dados"
  • "Mostre-me informações sobre o tamanho do banco de dados"
  • "Quais tabelas precisam de manutenção VACUUM?"

📖 Próximos Passos:

(NOTA) Visão Geral dos Dados de Teste de Exemplo

O script create-test-data.sql é executado pelo contêiner postgres-init-extensions (definido no docker-compose.yml) na primeira inicialização, gerando automaticamente bancos de dados de teste abrangentes para teste de ferramentas MCP:

Banco de DadosFinalidadeEsquema e TabelasEscala
ecommerceSistema de e-commercepublic: categories, products, customers, orders, order_items10 categorias, 500 produtos, 100 clientes, 200 pedidos, 400 itens de pedido
analyticsAnálise e relatóriospublic: page_views, sales_summary1.000 visualizações de página, 30 resumos de vendas
inventoryGerenciamento de armazémpublic: suppliers, inventory_items, purchase_orders10 fornecedores, 100 itens, 50 pedidos de compra
hr_systemGerenciamento de RHpublic: departments, employees, payroll5 departamentos, 50 funcionários, 150 registros de folha de pagamento

Usuários de teste criados: app_readonly, app_readwrite, analytics_user, backup_user

Otimizado para testes: Inchaço intencional de tabela, vários índices (usados/não usados), dados de séries temporais, relacionamentos complexos

Matriz de Compatibilidade de Ferramentas

Adaptação Automática: Todas as ferramentas funcionam de forma transparente nas versões suportadas - nenhuma configuração necessária!

🟢 Ferramentas Independentes de Extensão (Nenhuma Extensão Necessária)

Nome da FerramentaExtensões NecessáriasPG 12PG 13PG 14PG 15PG 16PG 17PG 18Visualizações/Tabelas do Sistema Usadas
get_server_info❌ Nenhuma✅✅✅✅✅✅✅version(), pg_extension
get_active_connections❌ Nenhuma✅✅✅✅✅✅✅pg_stat_activity
get_postgresql_config❌ Nenhuma✅✅✅✅✅✅✅pg_settings
get_database_list❌ Nenhuma✅✅✅✅✅✅✅pg_database
get_table_list❌ Nenhuma✅✅✅✅✅✅✅information_schema.tables
get_table_schema_info❌ Nenhuma✅✅✅✅✅✅✅information_schema.*, pg_indexes
get_database_schema_info❌ Nenhuma✅✅✅✅✅✅✅pg_namespace, pg_class, pg_proc
get_table_relationships❌ Nenhuma✅✅✅✅✅✅✅information_schema.* (restrições)
get_user_list❌ Nenhuma✅✅✅✅✅✅✅pg_user, pg_roles
get_index_usage_stats❌ Nenhuma✅✅✅✅✅✅✅pg_stat_user_indexes
get_database_size_info❌ Nenhuma✅✅✅✅✅✅✅pg_database_size()
get_table_size_info❌ Nenhuma✅✅✅✅✅✅✅pg_total_relation_size()
get_vacuum_analyze_stats❌ Nenhuma✅✅✅✅✅✅✅ Aprimoradopg_stat_user_tables
get_current_database_info❌ Nenhuma✅✅✅✅✅✅✅pg_database, current_database()
get_table_bloat_analysis❌ Nenhuma✅✅✅✅✅✅✅pg_stat_user_tables
get_database_bloat_overview❌ Nenhuma✅✅✅✅✅✅✅pg_stat_user_tables
get_autovacuum_status❌ Nenhuma✅✅✅✅✅✅✅pg_stat_user_tables
get_autovacuum_activity❌ Nenhuma✅✅✅✅✅✅✅pg_stat_user_tables
get_running_vacuum_operations❌ Nenhuma✅✅✅✅✅✅✅pg_stat_activity
get_vacuum_effectiveness_analysis❌ Nenhuma✅✅✅✅✅✅✅pg_stat_user_tables
get_lock_monitoring❌ Nenhuma✅✅✅✅✅✅✅pg_locks, pg_stat_activity
get_wal_status❌ Nenhuma✅✅✅✅✅✅✅pg_current_wal_lsn()
get_database_stats❌ Nenhuma✅✅✅✅✅✅✅ Aprimoradopg_stat_database
get_table_io_stats❌ Nenhuma✅✅✅✅✅✅✅pg_statio_user_tables
get_index_io_stats❌ Nenhuma✅✅✅✅✅✅✅pg_statio_user_indexes
get_database_conflicts_stats❌ Nenhuma✅✅✅✅✅✅✅pg_stat_database_conflicts

🚀 Ferramentas Cientes de Versão (Auto-Adaptáveis)

Nome da FerramentaExtensões NecessáriasPG 12PG 13PG 14PG 15PG 16PG 17PG 18Recursos Especiais
get_io_stats❌ Nenhuma✅ Básico✅ Básico✅ Básico✅ Básico✅ Aprimorado✅ Aprimorado✅ AprimoradoPG16+: suporte pg_stat_io; PG18+: colunas de bytes
get_bgwriter_stats❌ Nenhuma✅✅✅✅✅✅ Especial✅ AprimoradoPG17: Estatísticas separadas do checkpointer; PG18+: num_done, slru_written
get_replication_status❌ Nenhuma✅ Compatível✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ AprimoradoPG13+: wal_status, safe_wal_size; PG16+: receptor WAL aprimorado; PG17+: invalidation_reason, inactive_since
get_all_tables_stats❌ Nenhuma✅ Compatível✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ AprimoradoPG13+: rastreamento n_ins_since_vacuum para otimização de manutenção de vacuum
get_user_functions_stats⚙️ Config Necessária✅✅✅✅✅✅✅Requer track_functions=pl
get_wait_events❌ Nenhuma✅ Fallback✅ Fallback✅ Fallback✅ Fallback✅ Fallback✅ Nativo✅ NativoPG17+: catálogo pg_wait_events; PG12-16: fallback para esperas atuais pg_stat_activity
get_wal_summarizer_status❌ Nenhuma❌❌❌❌❌✅✅PG17+: monitoramento do resumidor de WAL para backups incrementais
get_async_io_status❌ Nenhuma❌❌❌❌❌❌✅PG18+: monitoramento do subsistema de I/O assíncrono pg_aios
get_per_backend_io_stats❌ Nenhuma❌❌❌❌❌❌✅PG18+: estatísticas de I/O e WAL por backend

🟡 Ferramentas Dependentes de Extensão (Extensões Necessárias)

Nome da FerramentaExtensão NecessáriaPG 12PG 13PG 14PG 15PG 16PG 17PG 18Notas
get_pg_stat_statements_top_queriespg_stat_statements✅ Compatível✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ AprimoradoPG12: total_time → total_exec_time; PG13+: total_exec_time nativo; PG17+: stats_since
get_pg_stat_monitor_recent_queriespg_stat_monitor✅ Compatível✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ Aprimorado✅ AprimoradoPG12: total_time → total_exec_time; PG13+: total_exec_time nativo

🆕 Recursos Específicos por Versão

PostgreSQL 17

  • Visão pg_wait_events: Catálogo nativo de eventos de espera com descrições (usado por get_wait_events)
  • WAL summarizer: Monitoramento para suporte a backup incremental (usado por get_wal_summarizer_status)
  • Aprimoramentos de replication slot: Colunas invalidation_reason e inactive_since (usadas por get_replication_status)
  • pg_stat_statements stats_since: Rastrear quando as estatísticas foram redefinidas pela última vez (usado por get_pg_stat_statements_top_queries)
  • Progresso do VACUUM: Rastreamento de vacuum de índice em visualizações de progresso (aprimoramento futuro para get_running_vacuum_operations)

PostgreSQL 18

  • Visão pg_aios: Monitoramento do subsistema de I/O assíncrono (usado por get_async_io_status)
  • Estatísticas de I/O por backend: Estatísticas individuais de I/O e WAL por backend (usadas por get_per_backend_io_stats)
  • Colunas de tempo VACUUM/ANALYZE: Tempo cumulativo de total_vacuum_time, total_autovacuum_time, total_analyze_time, total_autoanalyze_time (usado por get_vacuum_analyze_stats)
  • Colunas de bytes pg_stat_io: read_bytes, write_bytes, extend_bytes (usadas por get_io_stats)
  • Estatísticas de trabalhadores paralelos: parallel_workers_launched, parallel_workers_to_launch (usadas por get_database_stats)
  • Aprimoramentos do checkpointer: Colunas num_done, slru_written (usadas por get_bgwriter_stats)

Exemplos de Uso

Integração com Claude Desktop

(Recomendado) Adicione ao seu arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

"Mostre todas as conexões ativas em um formato de tabela HTML claro e legível." Claude Desktop Integration

"Mostre todos os relacionamentos para a tabela customers no banco de dados ecommerce como um diagrama Mermaid." Claude Desktop Integration

Instalação

Via PyPI (Recomendado)

# Install the package
pip install mcp-postgresql-ops

# Or with uv (faster)
uv add mcp-postgresql-ops

# Verify installation
mcp-postgresql-ops --help

Via Código-Fonte

# Clone the repository
git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

# Install with uv (recommended)
uv sync
uv run mcp-postgresql-ops --help

# Or with pip
pip install -e .
mcp-postgresql-ops --help

Configuração do MCP

Configuração do Claude Desktop

(Opcional) Executar com Código-Fonte Local:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_postgresql_ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

Executar o MCP-Server como Standalone

/w Pypi e uvx (Recomendado)

# Stdio mode
uvx --python 3.12 mcp-postgresql-ops \
  --type stdio

# HTTP mode
uvx --python 3.12 mcp-postgresql-ops
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

(Opcional) Configurar Múltiplas Instâncias do PostgreSQL

{
  "mcpServers": {
    "Postgresql-A": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "a.foo.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    },
    "Postgresql-B": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "b.bar.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres"
      }
    }
  }
}

/w Código-Fonte Local

# Method 1: Module execution (for development, requires PYTHONPATH)
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops \
  --type stdio

# Method 2: Direct script (after uv installation in project directory)
uv run mcp-postgresql-ops \
  --type stdio

# Method 3: Installed package script (after pip/uv install)
mcp-postgresql-ops \
  --type stdio

# HTTP mode examples:
# Development mode
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

# Production mode (after installation)
mcp-postgresql-ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

Argumentos de CLI

  • --type: Tipo de transporte (stdio ou streamable-http) - Padrão: stdio
  • --host: Endereço do host para transporte HTTP - Padrão: 127.0.0.1
  • --port: Número da porta para transporte HTTP - Padrão: 8000
  • --auth-enable: Habilitar autenticação por token Bearer para o modo streamable-http - Padrão: false
  • --secret-key: Chave secreta para autenticação por token Bearer (obrigatória quando a autenticação está habilitada)
  • --log-level: Nível de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL) - Padrão: INFO

Variáveis de Ambiente

VariávelDescriçãoPadrãoPadrão do Projeto
PYTHONPATHCaminho de pesquisa do módulo Python (necessário apenas no modo de desenvolvimento)-/app/src
MCP_LOG_LEVELVerbosidade do registro do servidor (DEBUG, INFO, WARNING, ERROR)INFOINFO
FASTMCP_TYPEProtocolo de transporte MCP (stdio para CLI, streamable-http para web)stdiostreamable-http
FASTMCP_HOSTEndereço de bind do servidor HTTP (0.0.0.0 para todas as interfaces)127.0.0.10.0.0.0
FASTMCP_PORTPorta do servidor HTTP para comunicação MCP80008000
REMOTE_AUTH_ENABLEHabilitar autenticação por token Bearer para o modo streamable-http (Padrão: false se indefinido/nulo/vazio)falsefalse
REMOTE_SECRET_KEYChave secreta para autenticação por token Bearer (obrigatória quando a autenticação está habilitada)-your-secret-key-here
PGSQL_VERSIONVersão principal do PostgreSQL para seleção da imagem Docker1717
PGDATADiretório de dados do PostgreSQL dentro do contêiner Docker (Não modificar)/var/lib/postgresql/data/data/db
POSTGRES_HOSTNome do host ou endereço IP do servidor PostgreSQL127.0.0.1host.docker.internal
POSTGRES_PORTNúmero da porta do servidor PostgreSQL543215432
POSTGRES_USERNome de usuário da conexão PostgreSQL (requer permissões de leitura)postgrespostgres
POSTGRES_PASSWORDSenha do usuário PostgreSQL (suporta caracteres especiais)changeme!@34changeme!@34
POSTGRES_DBNome padrão do banco de dados para conexõestestdbecommerce
POSTGRES_MAX_CONNECTIONSParâmetro de configuração max_connections do PostgreSQL200200
DOCKER_EXTERNAL_PORT_OPENWEBUIMapeamento de porta do host para o contêiner Open WebUI80803003
DOCKER_EXTERNAL_PORT_MCP_SERVERMapeamento de porta do host para o contêiner do servidor MCP808018003
DOCKER_EXTERNAL_PORT_MCPO_PROXYMapeamento de porta do host para o contêiner proxy MCPO80008003
DOCKER_INTERNAL_PORT_POSTGRESQLPorta interna do contêiner PostgreSQL54325432

Nota: POSTGRES_DB serve como banco de dados alvo padrão para operações quando nenhum banco de dados específico é especificado. Em ambientes Docker, se definido com um nome não padrão, este banco de dados será criado automaticamente durante a inicialização inicial do PostgreSQL.

Configuração de Porta: O contêiner PostgreSQL integrado usa o mapeamento de porta 15432:5432 onde:

  • POSTGRES_PORT=15432: Porta externa para acesso do host e conexões do servidor MCP
  • DOCKER_INTERNAL_PORT_POSTGRESQL=5432: Porta interna do contêiner (padrão do PostgreSQL)
  • Ao usar servidores PostgreSQL externos, defina POSTGRES_PORT para corresponder à porta real do seu servidor

Pré-requisitos

Extensões PostgreSQL Necessárias

Para mais detalhes, consulte a ## Matriz de Compatibilidade de Ferramentas

Nota: A maioria das ferramentas MCP funciona sem extensões PostgreSQL. Algumas ferramentas avançadas de análise de desempenho exigem as seguintes extensões:

-- Query performance statistics (required only for get_pg_stat_statements_top_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Advanced monitoring (optional, used by get_pg_stat_monitor_recent_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;

Configuração Rápida: Para novas instalações do PostgreSQL, adicione ao postgresql.conf:

shared_preload_libraries = 'pg_stat_statements'

Em seguida, reinicie o PostgreSQL e execute os comandos CREATE EXTENSION acima.

  • pg_stat_statements é necessária apenas para ferramentas de análise de consultas lentas.
  • pg_stat_monitor é opcional e usada para monitoramento de consultas em tempo real.
  • Todas as outras ferramentas funcionam sem essas extensões.

Requisitos Mínimos

  • PostgreSQL 12+ (testado com PostgreSQL 17 e 18)
  • Python 3.12
  • Acesso de rede ao servidor PostgreSQL
  • Permissões de leitura nos catálogos do sistema

Configuração PostgreSQL Necessária

⚠️ Configurações de Coleta de Estatísticas: Algumas ferramentas MCP exigem parâmetros de configuração específicos do PostgreSQL para coletar estatísticas. Escolha um dos seguintes métodos de configuração:

Ferramentas afetadas por essas configurações:

  • get_user_functions_stats: Requer track_functions = pl ou track_functions = all
  • get_table_io_stats & get_index_io_stats: Temporização mais precisa com track_io_timing = on
  • get_database_stats: Temporização de I/O aprimorada com track_io_timing = on

Verificação: Após aplicar qualquer método, verifique as configurações:

SELECT name, setting, context FROM pg_settings WHERE name IN ('track_activities', 'track_counts', 'track_io_timing', 'track_functions') ORDER BY name;

       name       | setting |  context  
------------------+---------+-----------
 track_activities | on      | superuser
 track_counts     | on      | superuser
 track_functions  | pl      | superuser
 track_io_timing  | on      | superuser
(4 rows)

Método 1: postgresql.conf (Recomendado para PostgreSQL Autogerenciado)

Adicione o seguinte ao seu postgresql.conf:

# Basic statistics collection (usually enabled by default)
track_activities = on
track_counts = on

# Required for function statistics tools
track_functions = pl    # Enables PL/pgSQL function statistics collection

# Optional but recommended for accurate I/O timing
track_io_timing = on    # Enables I/O timing statistics collection

Em seguida, reinicie o servidor PostgreSQL.

Método 2: Parâmetros de Inicialização do PostgreSQL

Para inicialização do PostgreSQL via Docker ou linha de comando:

# Docker example
docker run -d \
  -e POSTGRES_PASSWORD=mypassword \
  postgres:17 \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

# Direct postgres command
postgres -D /data \
  -c track_activities=on \
  -c track_counts=on \
  -c track_functions=pl \
  -c track_io_timing=on

Método 3: Configuração Dinâmica (AWS RDS, Azure, GCP, Serviços Gerenciados)

Para serviços PostgreSQL gerenciados onde você não pode modificar o postgresql.conf, use comandos SQL para alterar as configurações dinamicamente:

-- Enable basic statistics collection (usually enabled by default)
ALTER SYSTEM SET track_activities = 'on';
ALTER SYSTEM SET track_counts = 'on';

-- Enable function statistics collection (requires superuser privileges)
ALTER SYSTEM SET track_functions = 'pl';

-- Enable I/O timing statistics (optional but recommended)
ALTER SYSTEM SET track_io_timing = 'on';

-- Reload configuration without restart (run separately)
SELECT pg_reload_conf();

Alternativa para teste em nível de sessão:

-- Set for current session only (temporary)
SET track_activities = 'on';
SET track_counts = 'on';
SET track_functions = 'pl';
SET track_io_timing = 'on';

Nota: Ao usar ferramentas de linha de comando, execute cada instrução SQL separadamente para evitar erros de bloco de transação.

Compatibilidade RDS/Aurora

  • Este servidor é somente leitura e funciona com funções regulares no RDS/Aurora. Para análise avançada, habilite pg_stat_statements; pg_stat_monitor não está disponível em mecanismos gerenciados.
  • No RDS/Aurora, prefira o Grupo de Parâmetros do Banco de Dados em vez de ALTER SYSTEM para configurações persistentes. 
    -- Verify preload setting
SHOW shared_preload_libraries;

-- Enable extension in target DB
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- Recommended visibility for monitoring
GRANT pg_read_all_stats TO <app_user>;

Exemplos de Consultas

🟢 Ferramentas Independentes de Extensão (Sempre Disponíveis)

  • get_server_info
    • "Mostrar versão do servidor PostgreSQL e status das extensões."
    • "Verificar se pg_stat_statements está instalado."
  • get_active_connections
    • "Mostrar todas as conexões ativas."
    • "Listar sessões atuais com banco de dados e usuário."
  • get_postgresql_config
    • "Mostrar todos os parâmetros de configuração do PostgreSQL."
    • "Encontrar todas as configurações relacionadas à memória."
  • get_database_list
    • "Listar todos os bancos de dados e seus tamanhos."
    • "Mostrar lista de bancos de dados com informações do proprietário."
  • get_table_list
    • "Listar todas as tabelas no banco de dados ecommerce."
    • "Mostrar tamanhos de tabelas no schema public."
  • get_table_schema_info
    • "Mostrar informações detalhadas do schema para a tabela customers no banco de dados ecommerce."
    • "Obter detalhes de colunas e restrições para a tabela products no banco de dados ecommerce."
    • "Analisar estrutura da tabela com índices e chaves estrangeiras para a tabela orders no schema sales do banco de dados ecommerce."
    • "Mostrar visão geral do schema para todas as tabelas no schema public do banco de dados inventory."
    • 📋 Recursos: Tipos de coluna, restrições, índices, chaves estrangeiras, metadados da tabela
    • ⚠️ Obrigatório: o parâmetro database_name deve ser especificado
  • get_database_schema_info
    • "Mostrar todos os schemas no banco de dados ecommerce com seus conteúdos."
    • "Obter informações detalhadas sobre o schema sales no banco de dados ecommerce."
    • "Analisar estrutura do schema e permissões para o banco de dados inventory."
    • "Mostrar visão geral do schema com contagens de tabelas e tamanhos para o banco de dados hr_system."
    • 📋 Recursos: Proprietários de schema, permissões, contagens de objetos, tamanhos, conteúdos
    • ⚠️ Obrigatório: o parâmetro database_name deve ser especificado
  • get_table_relationships
    • "Mostrar todos os relacionamentos para a tabela customers no banco de dados ecommerce."
    • "Analisar relacionamentos de chave estrangeira para a tabela orders no schema sales do banco de dados ecommerce."
    • "Obter visão geral de relacionamentos em todo o banco de dados ecommerce."
    • "Encontrar todas as tabelas que referenciam a tabela products no banco de dados ecommerce."
    • "Mostrar relacionamentos entre schemas no banco de dados inventory."
    • 📋 Recursos: Relacionamentos de chave estrangeira (entrada/saída), dependências entre schemas, detalhes de restrições
    • ⚠️ Obrigatório: o parâmetro database_name deve ser especificado
    • 💡 Uso: Deixe table_name vazio para análise de relacionamentos em todo o banco de dados
  • get_user_list
    • "Listar todos os usuários do banco de dados e seus papéis."
    • "Mostrar permissões de usuário para um banco de dados específico."
  • get_index_usage_stats
    • "Analisar eficiência de uso de índices."
    • "Encontrar índices não utilizados no banco de dados atual."
  • get_database_size_info
    • "Mostrar análise de capacidade do banco de dados."
    • "Encontrar os maiores bancos de dados por tamanho."
  • get_table_size_info
    • "Mostrar análise de tamanho de tabelas e índices."
    • "Encontrar maiores tabelas em um schema específico."
  • get_vacuum_analyze_stats
    • "Mostrar operações recentes de VACUUM e ANALYZE."
    • "Listar tabelas que precisam de VACUUM."
  • get_current_database_info
    • "A qual banco de dados estou conectado?"
    • "Mostrar informações do banco de dados atual e detalhes de conexão."
    • "Exibir informações de codificação, collation e tamanho do banco de dados."
    • 📋 Recursos: Nome do banco de dados, codificação, collation, tamanho, limites de conexão
    • 🔧 PostgreSQL 12-18: Totalmente compatível, sem extensões necessárias
  • get_table_bloat_analysis
    • "Analisar inchaço (bloat) de tabelas no banco de dados atual."
    • "Mostrar proporções de tuplas mortas e estimativas de bloat para o padrão da tabela user_logs."
    • "Encontrar tabelas com alto bloat que precisam de manutenção VACUUM."
    • "Analisar bloat em schema específico com mínimo de 100 tuplas mortas."
    • 📋 Recursos: Proporções de tuplas mortas, estimativas de tamanho de bloat, recomendações de VACUUM, filtro por padrão
    • 🔧 PostgreSQL 12-18: Totalmente compatível, sem extensões necessárias
    • 💡 Uso: Abordagem independente de extensão usando pg_stat_user_tables
  • get_database_bloat_overview
    • "Mostrar resumo de bloat em todo o banco de dados por schema."
    • "Obter visão de alto nível da eficiência de armazenamento em todos os schemas."
    • "Identificar schemas que requerem atenção de manutenção."
    • 📋 Recursos: Agregação por schema, estimativas totais de bloat, status de manutenção
    • 🔧 PostgreSQL 12-18: Totalmente compatível, sem extensões necessárias
  • get_autovacuum_status
    • "Verificar configuração do autovacuum e condições de disparo."
    • "Mostrar tabelas que precisam de atenção imediata do autovacuum."
    • "Analisar percentuais de limite do autovacuum para o schema public."
    • "Encontrar tabelas se aproximando dos pontos de disparo do autovacuum."
    • 📋 Recursos: Análise de limites de disparo, classificação de urgência, status de configuração
    • 🔧 PostgreSQL 12-18: Totalmente compatível, sem extensões necessárias
    • 💡 Uso: Monitoramento de autovacuum independente de extensão usando pg_stat_user_tables
  • get_autovacuum_activity
    • "Mostrar padrões de atividade do autovacuum nas últimas 48 horas."
    • "Monitorar frequência e horário de execução do autovacuum."
    • "Encontrar tabelas com padrões irregulares de autovacuum."
    • "Analisar histórico recente de autovacuum e autoanalyze."
    • 📋 Recursos: Padrões de atividade, frequência de execução, análise de horários
    • 🔧 PostgreSQL 12-18: Totalmente compatível, sem extensões necessárias
    • 💡 Uso: Análise histórica de padrões de autovacuum
  • get_running_vacuum_operations
    • "Mostrar operações VACUUM e ANALYZE atualmente em execução."
    • "Monitorar operações de manutenção ativas e seu progresso."
    • "Verificar se alguma operação VACUUM está bloqueando consultas."
    • "Encontrar operações de manutenção de longa duração."
    • 📋 Recursos: Status de operações em tempo real, tempo decorrido, nível de impacto, detalhes do processo
    • 🔧 PostgreSQL 12-18: Totalmente compatível, sem extensões necessárias
    • 💡 Uso: Monitoramento de manutenção em tempo real usando pg_stat_activity
  • get_vacuum_effectiveness_analysis
    • "Analisar eficácia do VACUUM e padrões de manutenção."
    • "Comparar eficiência de VACUUM manual vs autovacuum."
    • "Encontrar tabelas com padrões de manutenção abaixo do ideal."
    • "Verificar frequência de VACUUM versus proporções de atividade da tabela."
    • 📋 Recursos: Análise de padrões de manutenção, avaliação de eficácia, proporções DML-para-VACUUM
    • 🔧 PostgreSQL 12-18: Totalmente compatível, sem extensões necessárias
    • 💡 Uso: Análise estratégica de VACUUM usando estatísticas existentes
  • get_lock_monitoring
    • "Mostrar todos os locks atuais e sessões bloqueadas."
    • "Mostrar apenas sessões bloqueadas com filtro granted=false."
    • "Monitorar locks por usuário específico com filtro de nome de usuário."
    • "Verificar locks exclusivos com filtro de modo."
  • get_wal_status
    • "Mostrar status do WAL e informações de arquivamento."
    • "Monitorar geração de WAL e posição atual do LSN."
  • get_replication_status
    • "Verificar conexões de replicação e status de lag."
    • "Monitorar slots de replicação e status do receptor WAL."
  • get_database_stats
    • "Mostrar métricas abrangentes de desempenho do banco de dados."
    • "Analisar proporções de commit de transações e estatísticas de I/O."
    • "Monitorar proporções de acerto do cache de buffer e uso de arquivos temporários."
  • get_bgwriter_stats
    • "Analisar desempenho e temporização de checkpoints."
    • "Mostrar desempenho de checkpoint."
    • "Mostrar estatísticas de eficiência do background writer."
    • "Monitorar alocação de buffers e padrões de fsync."
  • get_user_functions_stats
    • "Analisar desempenho de funções definidas pelo usuário."
    • "Mostrar contagens de chamadas de função e tempos de execução."
    • "Identificar gargalos de desempenho em funções personalizadas."
    • ⚠️ Requer: track_functions = pl no postgresql.conf
  • get_table_io_stats
    • "Analisar desempenho de I/O de tabelas e proporções de acerto de buffer."
    • "Identificar tabelas com desempenho ruim de cache de buffer."
    • "Monitorar estatísticas de I/O de tabelas TOAST."
    • 💡 Aprimorado com: track_io_timing = on para temporização precisa
  • get_index_io_stats
    • "Mostrar desempenho de I/O de índices e eficiência de buffer."
    • "Identificar índices que causam I/O excessivo em disco."
    • "Monitorar padrões de amigabilidade de cache de índices."
    • 💡 Aprimorado com: track_io_timing = on para temporização precisa
  • get_database_conflicts_stats
    • "Verificar conflitos de replicação em servidores standby."
    • "Analisar tipos de conflito e estatísticas de resolução."
    • "Monitorar padrões de cancelamento de consultas em servidores standby."
    • "Monitorar geração de WAL e posição atual do LSN."
  • get_replication_status
    • "Verificar conexões de replicação e status de lag."
    • "Monitorar slots de replicação e status do receptor WAL."

🚀 Ferramentas Cientes de Versão (Auto-Adaptáveis)

  • get_io_stats (Novo!)
    • "Mostrar estatísticas abrangentes de I/O." (PostgreSQL 16+ fornece detalhamento detalhado)
    • "Analisar estatísticas de I/O."
    • "Analisar eficiência do cache de buffer e temporização de I/O."
    • "Monitorar padrões de I/O por tipo de backend e contexto."
    • 📈 PG16+: pg_stat_io completo com temporização, tipos de backend e contextos
    • 📊 PG12-15: Fallback básico de pg_statio_* com proporções de acerto de buffer
  • get_bgwriter_stats (Aprimorado!)
    • "Mostrar desempenho do background writer e checkpoint."
    • 📈 PG17+: Estatísticas separadas de checkpointer e bgwriter via pg_stat_checkpointer
    • 📊 PG12-16: Estatísticas combinadas de bgwriter (inclui dados de checkpointer)
  • get_server_info (Aprimorado!)
    • "Mostrar versão do servidor e recursos de compatibilidade."
    • "Verificar compatibilidade do servidor."
    • "Verificar quais ferramentas MCP estão disponíveis nesta versão do PostgreSQL."
    • "Exibe matriz de disponibilidade de recursos e recomendações de upgrade."
  • get_all_tables_stats (Aprimorado!)
    • "Mostrar estatísticas abrangentes para todas as tabelas." (compatível com versões PG12-18)
    • "Incluir tabelas do sistema com parâmetro include_system=true."
    • "Analisar padrões de acesso a tabelas e necessidades de manutenção."
    • 📈 PG13+: Rastreia inserções desde o vacuum (n_ins_since_vacuum) para agendamento ideal de manutenção
    • 📊 PG12: Modo compatível com NULL para colunas não suportadas
  • get_wait_events (Novo!)
    • "Mostrar tipos e descrições de eventos de espera."
    • "Quais eventos de espera estão disponíveis nesta versão do PostgreSQL?"
    • 📈 PG17+: Catálogo nativo pg_wait_events com descrições completas
    • 📊 PG12-16: Fallback para esperas atuais de pg_stat_activity agrupadas por tipo
  • get_wal_summarizer_status (Novo! PG 17+)
    • "Mostrar status do summarizer WAL para backups incrementais."
    • "Monitorar progresso da sumarização WAL."
    • 📈 PG17+: Monitoramento do summarizer WAL via pg_get_wal_summarizer_state()
    • ❌ PG12-16: Não disponível (retorna mensagem informativa)
  • get_async_io_status (Novo! PG 18+)
    • "Mostrar status do subsistema de I/O assíncrono."
    • "Monitorar pg_aios para operações de I/O assíncrono."
    • 📈 PG18+: Visão pg_aios para monitoramento de I/O assíncrono
    • ❌ PG12-17: Não disponível (retorna mensagem informativa)
  • get_per_backend_io_stats (Novo! PG 18+)
    • "Mostrar estatísticas de I/O e WAL por backend."
    • "Analisar padrões de I/O por processo backend individual."
    • 📈 PG18+: Estatísticas de I/O por backend com estatísticas WAL
    • ❌ PG12-17: Não disponível (retorna mensagem informativa)

🟡 Ferramentas Dependentes de Extensão

  • get_pg_stat_statements_top_queries (Requer pg_stat_statements)
    • "Mostrar as 10 consultas mais lentas."
    • "Analisar consultas lentas no banco de dados inventory."
    • 📈 Compatível com versões: PG12 usa mapeamento total_time → total_exec_time; PG13+ usa colunas nativas
    • 💡 Entre versões: Adapta automaticamente a estrutura da consulta para compatibilidade com PostgreSQL 12-18
  • get_pg_stat_monitor_recent_queries (Opcional, usa pg_stat_monitor)
    • "Mostrar consultas recentes em tempo real."
    • "Monitorar atividade de consultas nos últimos 5 minutos."
    • 📈 Compatível com versões: PG12 usa mapeamento total_time → total_exec_time; PG13+ usa colunas nativas
    • 💡 Entre versões: Adapta automaticamente a estrutura da consulta para compatibilidade com PostgreSQL 12-18

💡 Dica Profissional: Todas as ferramentas suportam operações multi-banco de dados usando o parâmetro database_name. Isso permite que superusuários do PostgreSQL analisem e monitorem vários bancos de dados a partir de uma única instância do servidor MCP.

Solução de Problemas

Problemas de Conexão

  1. Verifique o status do servidor PostgreSQL
  2. Confirme os parâmetros de conexão no arquivo .env
  3. Garanta a conectividade de rede
  4. Verifique as permissões do usuário

Erros de Extensão

  1. Execute get_server_info para verificar o status das extensões
  2. Instale as extensões ausentes: 
    CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION pg_stat_monitor;
  3. Reinicie o PostgreSQL se necessário

Problemas de Configuração

  1. "Nenhum dado encontrado" para estatísticas de funções: Verifique a configuração de track_functions

    SHOW track_functions;  -- Should be 'pl' or 'all'

    Correção rápida para serviços gerenciados (AWS RDS, etc.):

    ALTER SYSTEM SET track_functions = 'pl';
SELECT pg_reload_conf();

  2. Dados de tempo de I/O ausentes: Habilite a coleta de timing

    SHOW track_io_timing;  -- Should be 'on'

    Correção rápida:

    ALTER SYSTEM SET track_io_timing = 'on';
SELECT pg_reload_conf();

  3. Aplique as alterações de configuração:

    • Autogerenciado: Adicione as configurações ao postgresql.conf e reinicie o servidor
    • Serviços gerenciados: Use ALTER SYSTEM SET + SELECT pg_reload_conf()
    • Teste temporário: Use SET parameter = value para a sessão atual
    • Gere alguma atividade no banco de dados para popular as estatísticas

Problemas de Desempenho

  1. Use os parâmetros limit para reduzir o tamanho do resultado
  2. Execute o monitoramento fora dos horários de pico
  3. Verifique a carga do banco de dados antes de executar a análise

Problemas de Compatibilidade de Versão

Para mais detalhes, consulte a ## Matriz de Compatibilidade de Ferramentas

  1. Execute a verificação de compatibilidade primeiro:

    # "Use get_server_info to check version and available features"

  2. Entendendo a disponibilidade de recursos:

    • PostgreSQL 18: Todos os recursos, incluindo I/O assíncrono, timing de VACUUM, estatísticas por backend
    • PostgreSQL 17: Estatísticas separadas de checkpointer, eventos de espera, resumidor de WAL
    • PostgreSQL 16: Visão pg_stat_io
    • PostgreSQL 14+: Rastreamento de consultas paralelas
    • PostgreSQL 12-13: Apenas funcionalidade principal

  3. Se uma ferramenta mostrar "Não disponível":

    • O recurso requer uma versão mais recente do PostgreSQL
    • A ferramenta usará automaticamente a melhor alternativa disponível
    • Considere atualizar o PostgreSQL para monitoramento aprimorado

Desenvolvimento

Testes e Desenvolvimento

# Clone and setup for development
git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops
uv sync

# Test with MCP Inspector (loads .env automatically)
./run-mcp-inspector-local.sh

# Direct execution methods:
# 1. Using uv run (recommended for development)
uv run mcp-postgresql-ops --log-level DEBUG

# 2. Module execution (requires PYTHONPATH)
PYTHONPATH=src python -m mcp_postgresql_ops --log-level DEBUG

# 3. After installation
mcp-postgresql-ops --log-level DEBUG

# Test version compatibility (requires different PostgreSQL versions)
# Modify POSTGRES_HOST in .env to point to different versions

Executando Testes

Duas suítes de testes estão disponíveis:

SuíteArquivoRequer Docker
Testes unitários (lógica de compatibilidade de versão)tests/test_version_compat.pyNão
Testes de integração (todas as ferramentas × PG 12–18)tests/test_tools_integration.pySim

uv run pytest inicia automaticamente os contêineres de teste Docker (PG 12–18), aguarda a inicialização completa, executa todos os testes e depois remove tudo.

# Run all tests (unit + integration) — Docker is managed automatically
uv run pytest -v

# Unit tests only (no Docker needed)
uv run pytest tests/test_version_compat.py -v

# Integration tests only
uv run pytest tests/test_tools_integration.py -v

Nota: O Docker deve estar em execução. A pilha de testes usa as portas 5412–5418 (PG 12–18).

Testes de Compatibilidade de Versão

O servidor MCP se adapta automaticamente às versões 12-18 do PostgreSQL. Para testar entre versões:

  1. Configure bancos de dados de teste: Diferentes versões do PostgreSQL (12, 14, 15, 16, 17, 18)
  2. Execute testes de compatibilidade: Aponte para cada versão e verifique o comportamento da ferramenta
  3. Verifique a detecção de recursos: Garanta a detecção correta de versão e a disponibilidade de recursos
  4. Verifique o comportamento de fallback: Confirme a degradação graciosa em versões mais antigas

Notas de Segurança

  • Todas as ferramentas são somente leitura - sem capacidade de modificação de dados
  • Informações sensíveis (senhas) são mascaradas nas saídas
  • Sem execução direta de SQL - apenas consultas predefinidas
  • Segue o princípio do menor privilégio

Contribuindo

🤝 Tem ideias? Encontrou bugs? Quer adicionar recursos legais?

Estamos sempre animados em receber novos colaboradores! Seja corrigindo um erro de digitação, adicionando uma nova ferramenta de monitoramento ou melhorando a documentação - cada contribuição torna este projeto melhor.

Formas de contribuir:

  • 🐛 Relate problemas ou bugs
  • 💡 Sugira novos recursos de monitoramento do PostgreSQL
  • 📝 Melhore a documentação
  • 🚀 Envie pull requests
  • ⭐ Dê uma estrela no repositório se achar útil!

Dica profissional: O código foi projetado para ser super amigável para adicionar novas ferramentas. Confira as funções existentes @mcp.tool() em mcp_main.py.

Documentação Swagger do MCPO

[URL do Swagger do MCPO] http://localhost:8003/postgresql-ops/docs

MCPO Swagger APIs

🔐 Segurança e Autenticação

Autenticação com Token Bearer

Para o modo streamable-http, este servidor MCP suporta autenticação com token Bearer para proteger o acesso remoto. Isso é especialmente importante ao executar o servidor em ambientes de produção.

Política Padrão: REMOTE_AUTH_ENABLE assume o valor padrão false se indefinido, nulo ou vazio. Isso garante compatibilidade retroativa e evita erros de inicialização quando a variável não está definida.

Configuração

Habilitar Autenticação:

# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=my-test-secret-key-12345

Ou via CLI:

# Module method
python -m mcp_postgresql_ops --type streamable-http --auth-enable --secret-key my-test-secret-key-12345

# Script method
mcp-postgresql-ops --type streamable-http --auth-enable --secret-key my-test-secret-key-12345

Níveis de Segurança

  1. Modo stdio (Padrão): Acesso apenas local, sem necessidade de autenticação
  2. streamable-http + REMOTE_AUTH_ENABLE=false: Acesso remoto sem autenticação ⚠️ NÃO RECOMENDADO para produção
  3. streamable-http + REMOTE_AUTH_ENABLE=true: Acesso remoto com autenticação por token Bearer ✅ RECOMENDADO para produção

Configuração do Cliente

Quando a autenticação está habilitada, os clientes MCP devem incluir o token Bearer no cabeçalho Authorization:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer my-test-secret-key-12345"
      }
    }
  }
}

Boas Práticas de Segurança

  • Sempre habilite a autenticação ao usar o modo streamable-http em produção
  • Use chaves secretas fortes e geradas aleatoriamente (32+ caracteres recomendados)
  • Use HTTPS quando possível (configure um proxy reverso com SSL/TLS)
  • Restrinja o acesso à rede usando firewalls ou políticas de rede
  • Rotacione as chaves secretas regularmente para maior segurança
  • Monitore os logs de acesso para tentativas de acesso não autorizado

Tratamento de Erros

Quando a autenticação falha, o servidor retorna:

  • 401 Não Autorizado para tokens ausentes ou inválidos
  • Mensagens de erro detalhadas em formato JSON para depuração

🚀 Adicionando Ferramentas Personalizadas

Este servidor MCP foi projetado para fácil extensibilidade. Siga estes 4 passos simples para adicionar suas próprias ferramentas personalizadas:

Guia Passo a Passo

1. Adicione Funções Auxiliares (Opcional)

Adicione funções de dados reutilizáveis ao src/mcp_postgresql_ops/functions.py:

async def get_your_custom_data(target_database: str = None, limit: int = 20) -> List[Dict[str, Any]]:
    """Your custom data retrieval function."""
    try:
        # Example implementation - adapt to your PostgreSQL needs
        query = """
        SELECT 
            schemaname,
            tablename,
            attname as column_name,
            n_distinct,
            most_common_vals,
            most_common_freqs
        FROM pg_stats 
        WHERE schemaname NOT IN ('information_schema', 'pg_catalog')
        ORDER BY schemaname, tablename, attname
        LIMIT $1
        """
        
        results = await execute_query(query, [limit], database=target_database)
        return results
        
    except Exception as e:
        logger.error(f"Failed to get custom data: {e}")
        raise

2. Crie Sua Ferramenta MCP

Adicione sua função de ferramenta ao src/mcp_postgresql_ops/mcp_main.py:

@mcp.tool()
async def get_your_custom_analysis(limit: int = 50, database_name: Optional[str] = None) -> str:
    """
    [Tool Purpose]: Brief description of what your tool does
    
    [Exact Functionality]:
    - Feature 1: Data aggregation and analysis
    - Feature 2: Database monitoring and insights
    - Feature 3: Performance metrics and reporting
    
    [Required Use Cases]:
    - When user asks "your specific analysis request"
    - Your PostgreSQL-specific monitoring needs
    
    Args:
        limit: Maximum results (1-100)
        database_name: Target database name (optional, uses default if not specified)
    
    Returns:
        Formatted analysis results
    """
    try:
        # Always validate input limits
        limit = max(1, min(limit, 100))
        
        # Get your custom data
        results = await get_your_custom_data(target_database=database_name, limit=limit)
        
        if not results:
            return "No data found for custom analysis."
        
        # Format and return results
        return format_table_data(results, f"Custom Analysis Results (Top {len(results)})")
        
    except Exception as e:
        logger.error(f"Failed to get custom analysis: {e}")
        return f"Error: {str(e)}"

3. Atualize os Imports

Adicione sua função auxiliar à seção de imports em src/mcp_postgresql_ops/mcp_main.py (por volta da linha 30):

from .functions import (
    execute_query,
    execute_single_query,
    format_table_data,
    format_bytes,
    format_duration,
    get_server_version,
    check_extension_exists,
    get_pg_stat_statements_data,
    get_pg_stat_monitor_data,
    sanitize_connection_info,
    read_prompt_template,
    parse_prompt_sections,
    get_current_database_name,
    POSTGRES_CONFIG,
    get_your_custom_data,  # Add your new function here
)

4. Atualize o Modelo de Prompt (Recomendado)

Adicione a descrição da sua ferramenta ao src/mcp_postgresql_ops/prompt_template.md para melhor reconhecimento de linguagem natural:

### **Your Custom Analysis Tool**

### X. **get_your_custom_analysis**
**Purpose**: Brief description of what your tool does
**Usage**: "Show me your custom analysis" or "Get custom analysis for database_name"
**Features**: Data aggregation, database monitoring, performance metrics
**Optional**: `database_name` parameter for specific database analysis
**Limit**: Results limited to 1-100 records for performance

5. Teste Sua Ferramenta

# Local testing with MCP Inspector
./run-mcp-inspector-local.sh

# Or test with Docker stack
docker-compose up -d
docker-compose logs -f mcp-server

# Test with natural language queries:
# "Show me your custom analysis"
# "Get custom analysis for ecommerce database"
# "Analyze custom data with limit 25"

Notas Importantes

  • Suporte a Múltiplos Bancos de Dados: Todas as ferramentas suportam o parâmetro opcional database_name para direcionar bancos de dados específicos
  • Validação de Entrada: Sempre valide os parâmetros limit com max(1, min(limit, 100))
  • Tratamento de Erros: Retorne mensagens de erro amigáveis ao usuário em vez de lançar exceções
  • Registro (Logging): Use logger.error() para depuração enquanto retorna mensagens de erro limpas aos usuários
  • Compatibilidade com PostgreSQL: Suas consultas personalizadas devem funcionar em PostgreSQL 12-18
  • Dependências de Extensão: Se sua ferramenta exigir extensões específicas, verifique a disponibilidade com check_extension_exists()

Padrões Avançados

Para consultas cientes de versão ou recursos dependentes de extensão, veja ferramentas existentes como get_pg_stat_statements_top_queries para padrões de referência.

É isso! Sua ferramenta personalizada está pronta para uso com consultas em linguagem natural através de qualquer cliente MCP.

Licença

Use, modifique e distribua livremente sob a Licença MIT.

⭐ Outros Projetos

Outros servidores MCP do mesmo autor: