MCPg - Production-grade PostgreSQL MCP Server

Servidor do Protocolo de Contexto de Modelo PostgreSQL seguro por padrão para agentes de IA.

Documentação

MCPg

Um servidor Model Context Protocol de nível de produção para PostgreSQL. Ele permite que agentes de IA inspecionem, consultem, operem e ajustem com segurança um banco de dados Postgres — 254 ferramentas que abrangem introspecção de catálogo, inteligência de consultas, SQL em linguagem natural, diffs estruturais, busca híbrida, consultas em grafo, movimentação de dados, operações ao vivo e muito mais.

Experimente ao vivo: aponte um cliente MCP — ou o MCP Inspector — para o endpoint de demonstração hospedado, somente leitura https://devopam-mcpg-demo.hf.space/mcp. Ele serve ferramentas de leitura contra dados de demonstração descartáveis; para uso real, execute o MCPg ao lado do seu próprio banco de dados (veja Início rápido).

📍 Listado em

Aspecto	MCPg
Segurança	Somente leitura por padrão + validação AST
Transporte	stdio + HTTP/SSE
Instalação	`pip install mcpg`
Versões do Postgres	14–19
Diferencial-chave	Observabilidade de produção + multi-inquilinos

Por que MCPg

Seguro por padrão. Modo de acesso somente leitura. Toda instrução SQL fornecida pelo usuário é analisada por meio de uma lista de permissões AST validada antes da execução. A interpolação de identificadores passa por uma expressão regular estrita [A-Za-z_][A-Za-z0-9_]* — uma restrição de design que significa que a entrada do usuário nunca chega ao banco de dados por concatenação de strings. Recursos como DDL, shell e LISTEN/NOTIFY ficam desativados até que você opte por ativá-los. Cada ferramenta publica MCP ToolAnnotations (readOnlyHint, openWorldHint) derivados dessas mesmas portas, para que os clientes possam aprovar automaticamente leituras e controlar gravações sem adivinhar.
Um servidor, ampla superfície. Acesso a dados de aplicativos (consultas, busca, cursores, NL→SQL) e operações de nível DBA (verificações de integridade, ajuste de índices, análise EXPLAIN, locks, vacuum, dumps, réplicas, migrações) em um único servidor MCP. Os agentes não precisam alternar ferramentas para alternar tarefas.
Tudo nativo do PostgreSQL. Sem ORM, sem imposto de abstração — usa psycopg3 diretamente, fala com todas as visualizações de sistema pg_*, integra-se com TimescaleDB, pgvector, PostGIS, Apache AGE e pg_stat_statements quando disponíveis, e degrada graciosamente quando não estão.
Formato de produção, não de demonstração. Pool de conexões, multi-inquilinos SET ROLE por solicitação, roteamento de réplica de leitura com detecção de host degradado, cursores no lado do servidor com conexões dedicadas, limitação de taxa, trilha de auditoria com redação por regex, aplicação de TLS PG na inicialização, autenticação de portador OIDC JWT, tempo limite de instrução / lock por sessão.
Observabilidade integrada. Endpoint Prometheus /metrics no transporte HTTP expõe mcpg_tool_calls_total{tool,status} + mcpg_tool_duration_seconds. Cada chamada de ferramenta registra um evento de auditoria estruturado com argumentos com credenciais redigidas.
Orientado a testes, multi-versão. Mais de 2.500 testes unitários, além de uma suíte de integração que roda contra um contêiner PostgreSQL real no CI — a matriz cobre PG 14, 15, 16, 17, 18 a cada push, além de PG 19 (beta) como entrada experimental (não bloqueante) rastreada na issue #120.

Instalação

Do PyPI (recomendado)

pip install mcpg
# or, in an isolated venv exposed globally:
uv tool install mcpg

Verifique:

mcpg --version

Docker

Baixe a imagem pré-construída do GitHub Container Registry (publicada a cada release com tag — :latest rastreia a mais recente, ou fixe uma versão como :0.6.5):

docker pull ghcr.io/devopam/mcpg:latest
docker run --rm --name mcpg -p 8000:8000 \
    -e MCPG_DATABASE_URL=postgresql://user:pass@host:5432/db \
    -e MCPG_ACCESS_MODE=read-only \
    ghcr.io/devopam/mcpg:latest

No Windows PowerShell, substitua o \ final por um acento grave ` (ou coloque o comando em uma única linha); o guia de instalação tem blocos prontos para copiar para Linux/macOS, PowerShell e Command Prompt.

Ou construa você mesmo a partir do código-fonte:

docker build -t mcpg https://github.com/devopam/MCPg.git

Imagem multi-estágio: o estágio de runtime remove o toolchain de build, executa como uid=10001 / gid=10001 com shell nologin, arquivos de aplicação de propriedade da raiz e somente leitura para o usuário de runtime.

Do código-fonte (desenvolvedores)

git clone https://github.com/devopam/MCPg && cd MCPg
uv sync

uv sync cria um venv com todas as dependências de runtime + desenvolvimento e expõe o script de console mcpg.

Mais detalhes no Guia de Instalação.

Início rápido

Instalações com um clique: — configuração para Windsurf, JetBrains, Zed, Cline, Antigravity, Qwen Code, Perplexity, ChatGPT, Copilot Studio, Continue e clientes HTTP no guia de integrações.

Instalação com um clique no Claude Desktop (.mcpb)

Baixe mcpg-<version>.mcpb do último release e dê dois cliques nele (ou arraste-o para Configurações do Claude Desktop → Extensões). Você será solicitado a fornecer sua URL de conexão PostgreSQL — armazenada no chaveiro do sistema operacional — e um modo de acesso (padrão: somente leitura). Essa é a instalação completa: o pacote tem ~2 kB e o host resolve o release mcpg fixado do PyPI para sua plataforma.

Ou configure manualmente (transporte stdio)

Coloque isto no seu claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "mcpg": {
      "command": "uvx",
      "args": ["mcpg"],
      "env": {
        "MCPG_DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Reinicie o Claude Desktop. O conjunto de ferramentas MCPg agora está disponível para o modelo. Você pode perguntar ao Claude coisas como:

"Quais schemas existem neste banco de dados? Para cada um, resuma as três maiores tabelas."

"Por que esta consulta está lenta? SELECT * FROM orders WHERE customer_id = 42 ORDER BY created_at DESC"

Sem dados interessantes ainda? Semeie o conjunto de dados de demonstração

MCPG_DATABASE_URL=postgresql://... mcpg --demo

Um comando semeia um pequeno conjunto de dados de e-commerce selecionado (3.000 pedidos, 900 avaliações de produtos, falhas plantadas deliberadamente) em um schema mcpg_demo — projetado para que o consultor de índices, a análise de plano de consulta, a busca em texto completo, a auditoria de PII e a projeção em grafo tenham algo real para encontrar na sua primeira tentativa. Veja o passeio guiado para um passo a passo capturado, e remova-o a qualquer momento com mcpg --demo-drop.

Execute como servidor HTTP (para integrações de IDE, aplicativos web, etc.)

MCPG_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb \
MCPG_TRANSPORT=streamable-http \
MCPG_HTTP_PORT=8000 \
mcpg

Em seguida, aponte qualquer cliente compatível com MCP para http://localhost:8000/mcp (ou /sse para o transporte SSE). O transporte HTTP se recusa a iniciar a menos que esteja autenticado — defina MCPG_HTTP_AUTH_TOKEN=... para um bearer estático, ou MCPG_AUTH_MODE=oidc para validação JWT completa contra um emissor OIDC. Para executar deliberadamente sem autenticação (não recomendado), defina MCPG_HTTP_ALLOW_UNAUTHENTICATED=true.

Configuração

O MCPg é configurado inteiramente por meio de variáveis de ambiente — sem arquivo de configuração, sem flags (os --version / --demo / --demo-drop da CLI são comandos únicos, não configuração). A única obrigatória é MCPG_DATABASE_URL; todo o resto tem um padrão seguro.

Cenários comuns

Cenário	Defina
Exploração local, somente leitura	`MCPG_DATABASE_URL`
Acesso a dados de aplicativo com leitura/gravação	`MCPG_ACCESS_MODE=restricted`
Kit de ferramentas DBA (DDL, vacuum, etc.)	`MCPG_ACCESS_MODE=unrestricted` + `MCPG_ALLOW_DDL=true`
Transporte HTTP com autenticação bearer	`MCPG_TRANSPORT=streamable-http` + `MCPG_HTTP_AUTH_TOKEN=…`
SaaS multi-inquilino	`MCPG_DEFAULT_ROLE=tenant_a` + `MCPG_ALLOWED_ROLES=tenant_a,tenant_b,…`
Distribuição de réplica de leitura	`MCPG_REPLICA_URLS=postgresql://…?sslmode=require,postgresql://…?sslmode=require`
NL→SQL — provedor único	Defina qualquer chave de fornecedor (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `HF_TOKEN`, … — 22 provedores integrados). O MCPg escolhe automaticamente o padrão.
NL→SQL — vários provedores, chamador escolhe	Defina todas as chaves de fornecedor que deseja ativar. Cada chamada para `translate_nl_to_sql` pode passar `provider="…"` (qualquer integrado ou personalizado configurado).

Referência completa

Núcleo

Variável	Padrão	Descrição
`MCPG_DATABASE_URL`	obrigatória	DSN PostgreSQL primário. Suporta formas URI (`postgresql://…`) e palavra-chave (`host=… user=…`). Hosts remotos exigem `sslmode=require` (ou mais forte).
`MCPG_ACCESS_MODE`	`read-only`	`read-only` \| `restricted` (permite ferramentas de gravação) \| `unrestricted` (também desbloqueia ferramentas DBA quando combinado com as variáveis de porta).
`MCPG_TRANSPORT`	`stdio`	`stdio` (padrão, para Claude Desktop) \| `streamable-http` \| `sse`.
`MCPG_LOG_LEVEL`	`INFO`	`DEBUG` \| `INFO` \| `WARNING` \| `ERROR` \| `CRITICAL`.
`MCPG_HTTP_HOST`	`127.0.0.1`	Endereço de bind para transportes HTTP. Defina como `0.0.0.0` dentro de contêineres.
`MCPG_HTTP_PORT`	`8000`	Porta de escuta para transportes HTTP (1–65535).

Portas de capacidade (opt-in para ferramentas de maior raio de impacto)

Variável	Padrão	Descrição
`MCPG_ALLOW_DDL`	`false`	Expõe ferramentas DDL (`run_ddl`, `create_graph`, `drop_graph`, ferramentas de hypertable, ferramentas de migração). Exige `MCPG_ACCESS_MODE=unrestricted`.
`MCPG_ALLOW_SHELL`	`false`	Expõe ferramentas com suporte a subprocesso (`dump_database`, `restore_database`, `run_pg_binary`). Os binários de cliente PG necessários devem estar em `PATH`.
`MCPG_ALLOW_LISTEN`	`false`	Expõe ferramentas `LISTEN/NOTIFY` (`subscribe_channel`, `poll_notifications`, `unsubscribe_channel`, `list_notification_subscriptions`).

Autenticação (somente transportes HTTP)

Variável	Padrão	Descrição
`MCPG_AUTH_MODE`	`static`	`static` (compara bearer com `MCPG_HTTP_AUTH_TOKEN`) \| `oidc` (validação JWT completa).
`MCPG_HTTP_AUTH_TOKEN`	—	Token bearer obrigatório quando `MCPG_AUTH_MODE=static`. Comparação em tempo constante. O transporte HTTP se recusa a iniciar (`ConfigError`) a menos que isto, `MCPG_AUTH_MODE=oidc` ou `MCPG_HTTP_ALLOW_UNAUTHENTICATED=true` esteja definido.
`MCPG_HTTP_ALLOW_UNAUTHENTICATED`	`false`	Opt-out explícito da verificação de autenticação fail-closed do transporte HTTP. Registrado em log de forma ruidosa a cada inicialização quando definido; não recomendado.
`MCPG_OIDC_ISSUER`	—	URL do emissor OIDC (obrigatória quando `MCPG_AUTH_MODE=oidc`).
`MCPG_OIDC_AUDIENCE`	—	Claim `aud` esperado (obrigatório quando `MCPG_AUTH_MODE=oidc`).
`MCPG_OIDC_JWKS_URL`	descoberto	Substitui o endpoint JWKS (auto-descoberto do `.well-known` do emissor caso contrário).
`MCPG_OIDC_ROLE_CLAIM`	—	Claim JWT cujo valor se torna o papel PG por solicitação (`SET LOCAL ROLE`). Compõe-se com o driver de locação.

Endurecimento HTTP (somente transportes HTTP)

Variável	Padrão	Descrição
`MCPG_HTTP_MAX_BODY_BYTES`	`1048576`	(1 MiB) Corpos de solicitação acima disso recebem um `413`. Conta bytes transmitidos, então um `Content-Length` ausente/incorreto não pode contorná-lo.
`MCPG_HTTP_ALLOWED_ORIGINS`	—	Lista de permissões CORS separada por vírgulas. Não definido = sem middleware CORS (nenhum cabeçalho de origem cruzada emitido).
`MCPG_HTTP_HSTS_MAX_AGE`	`63072000`	`Strict-Transport-Security` max-age (2 anos, recomendação atual da OWASP). `0` desativa o cabeçalho HSTS. Cabeçalhos de segurança (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy) são sempre adicionados, a menos que o aplicativo já os tenha definido.
`MCPG_HTTP_REQUEST_TIMEOUT_SECONDS`	`0`	Limite de tempo de parede por solicitação (`504` na expiração). `0` = desativado. Deixe desativado se você depender de fluxos SSE / HTTP transmitível de longa duração — um limite rígido também os encerra.
`MCPG_HTTP_TRUSTED_HOSTS`	—	Lista separada por vírgulas de valores de cabeçalho `Host` permitidos (curingas como `*.example.com` suportados). Não definido = sem validação de cabeçalho de host (comportamento atual). Quando definido, solicitações com Host não correspondente recebem um `400` via `TrustedHostMiddleware` do Starlette.

Multi-inquilinos (`SET ROLE`)

Variável	Padrão	Descrição
`MCPG_DEFAULT_ROLE`	—	Papel PG estático aplicado a cada consulta. Validado como identificador.
`MCPG_ALLOWED_ROLES`	—	Lista de permissões separada por vírgulas. Quando definida, o cabeçalho `X-MCPG-Role` / a declaração de papel OIDC deve estar nesta lista.

Réplicas de leitura

Variável	Padrão	Descrição
`MCPG_REPLICA_URLS`	—	DSNs de réplica separados por vírgulas. Consultas `force_readonly` fazem round-robin entre réplicas saudáveis; fallback para a primária em caso de falha; janela de nova tentativa de réplica degradada de 30 s.

Múltiplos bancos de dados (secundários somente leitura)

Variável	Padrão	Descrição
`MCPG_SECONDARY_DATABASE_URLS`	—	Entradas `name=dsn` separadas por vírgulas ou novas linhas nomeando bancos de dados adicionais somente leitura que este servidor pode atender (ex.: `analytics=postgresql://…?sslmode=require,reporting=postgresql://…?sslmode=require`). Ferramentas com capacidade de leitura aceitam um argumento opcional `database` selecionando um secundário pelo nome; omita-o para o primário. Secundários são somente leitura — imposto pelo PostgreSQL (cada consulta roda em uma transação `READ ONLY`), então gravações / DDL / shell / migrate sempre visam o primário. Nomes devem ser identificadores simples (`[a-z0-9_]+`), únicos, e não `primary` (o id reservado de `MCPG_DATABASE_URL`). Mesmas regras de TLS que o DSN primário. Chame `list_databases` para descobrir os ids configurados e sua acessibilidade.

Pool / timeouts / TLS

Variável	Padrão	Descrição
`MCPG_POOL_MIN_SIZE`	`1`	Conexões mínimas do pool.
`MCPG_POOL_MAX_SIZE`	`5`	Conexões máximas do pool. Deve ser ≥ `MCPG_POOL_MIN_SIZE`.
`MCPG_STATEMENT_TIMEOUT_MS`	`30000`	`statement_timeout` por sessão definido no checkout da conexão. Consultas descontroladas se autoterminam.
`MCPG_LOCK_TIMEOUT_MS`	`5000`	`lock_timeout` por sessão. Esperas de lock penduradas se autoterminam.
`MCPG_ENABLE_ANALYTICAL_QUERIES`	`true`	Expor `run_analytical_query` (leituras de longa duração em um pool isolado). Defina `false` para retirar a ferramenta.
`MCPG_ANALYTICAL_TIMEOUT_MS`	`120000`	Orçamento padrão por chamada para `run_analytical_query` (2 min).
`MCPG_ANALYTICAL_MAX_TIMEOUT_MS`	`600000`	Teto rígido para `run_analytical_query`; um `timeout_ms` por chamada é limitado a este valor (10 min). Deve ser ≥ `MCPG_ANALYTICAL_TIMEOUT_MS`.
`MCPG_ANALYTICAL_MAX_CONCURRENCY`	`2`	Tamanho do pool analítico isolado — máximo de chamadas `run_analytical_query` simultâneas.
`MCPG_ALLOW_INSECURE_TLS`	`false`	Ignorar a verificação TLS de inicialização que recusa DSNs remotos sem `sslmode=require` (ou mais forte). Hosts de loopback estão sempre isentos.
`MCPG_SHUTDOWN_DRAIN_SECONDS`	`30`	No SIGTERM, aguardar até este tempo para chamadas de ferramenta em andamento terminarem antes de fechar o pool e cursores.

Ferramentas de subprocesso (somente `MCPG_ALLOW_SHELL=true`)

Variável	Padrão	Descrição
`MCPG_SHELL_TIMEOUT_SEC`	`60`	Tempo máximo de parede para invocações `pg_dump` / `pg_restore` / `psql`.
`MCPG_SHELL_MAX_OUTPUT_BYTES`	`67108864`	(64 MiB) Limite no stdout capturado por chamada de subprocesso.
`MCPG_SUBPROCESS_BIN_ALLOWLIST`	—	Diretórios absolutos separados por vírgulas sob os quais o `pg_dump` / `pg_restore` / `psql` resolvido deve estar. Vazio = confiar em `PATH`. Impede um shim de PATH desses binários.
`MCPG_SUBPROCESS_CPU_SECONDS`	—	`RLIMIT_CPU` por filho (segundos). Somente POSIX; não definido = herdar.
`MCPG_SUBPROCESS_MEMORY_MB`	—	`RLIMIT_AS` por filho (MiB). Somente POSIX; não definido = herdar.

LISTEN/NOTIFY (somente `MCPG_ALLOW_LISTEN=true`)

Variável	Padrão	Descrição
`MCPG_LISTEN_QUEUE_MAX`	`1000`	Buffer por canal; notificações mais antigas são descartadas em caso de estouro.

Auditoria

Variável	Padrão	Descrição
`MCPG_AUDIT_PERSIST`	`false`	Quando verdadeiro, cada chamada `run_write` / `run_ddl` persiste em uma tabela `mcpg_audit.events` (criada automaticamente de forma idempotente).
`MCPG_AUDIT_REDACT_KEYS`	—	Fragmentos de regex separados por vírgulas adicionados ao padrão de nomes de segredos (os padrões já cobrem `password`, `passwd`, `secret`, `token`, `api[_-]?key`, `bearer`, `authorization`, `database_url`, `dsn`, `conninfo`).
`MCPG_AUDIT_INTEGRITY`	`false`	Quando verdadeiro, cada evento persistido é assinado com um HMAC encadeado sobre o evento anterior; a ferramenta `verify_audit_chain` percorre a cadeia e relata a primeira quebra. Requer `MCPG_AUDIT_HMAC_KEY`.
`MCPG_AUDIT_HMAC_KEY`	—	Chave secreta para a cadeia HMAC de auditoria. Obrigatória quando `MCPG_AUDIT_INTEGRITY=true`. Nunca aparece em `repr`/logs.

Backend de segredos

Por padrão, cada segredo é lido diretamente do ambiente. Defina MCPG_SECRETS_BACKEND=file para carregar chaves de API / token de portador / chave HMAC de um arquivo montado — um nome no arquivo vence; qualquer coisa ausente cai de volta para a variável de ambiente, então arquivos parciais funcionam.

Variável	Padrão	Descrição
`MCPG_SECRETS_BACKEND`	`env`	`env` (ler cada segredo do ambiente) \| `file` (sobrepor um arquivo de segredos sobre o ambiente).
`MCPG_SECRETS_FILE_PATH`	—	Obrigatório quando `MCPG_SECRETS_BACKEND=file`. Caminho para um mapa `name → value` simples: JSON sempre, ou YAML (`.yaml`/`.yml`) quando PyYAML está instalado. Cobre `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY` / `MCPG_NL2SQL_API_KEY`, `MCPG_HTTP_AUTH_TOKEN`, e `MCPG_AUDIT_HMAC_KEY`.

Limitação de taxa

Variável	Padrão	Descrição
`MCPG_RATE_LIMIT_ENABLED`	`true`	Limitação de taxa por ferramenta com token-bucket. Defina para `false` para restaurar o comportamento ilimitado anterior à mudança de quebra.
`MCPG_RATE_LIMIT_MAX_REQUESTS`	`60`	Limite global por janela em todas as ferramentas.
`MCPG_RATE_LIMIT_WINDOW_SECONDS`	`60`	Comprimento da janela para a cota global.
`MCPG_RATE_LIMIT_HEAVY_MAX`	`5`	Limite para ferramentas pesadas (`run_write`, `run_ddl`, `dump_database`, etc.).
`MCPG_RATE_LIMIT_HEAVY_WINDOW`	`60`	Comprimento da janela para a cota de ferramentas pesadas.

Cache e flags de recursos

Variável	Padrão	Descrição
`MCPG_CACHE_ENABLED`	`true`	Ativar ou desativar a camada de cache adaptativa.
`MCPG_CACHE_TTL_SECONDS`	`300`	Time-To-Live padrão do cache em segundos.
`MCPG_CACHE_MAXSIZE`	`1024`	Limite máximo de capacidade LRU para o cache em memória.
`MCPG_REDIS_URL`	—	String de conexão opcional do backend Redis para cache externo e multi-nó.
`MCPG_ENABLE_HEAVY_DIAGNOSTICS`	`true`	Alternar ferramentas de diagnóstico, diagrama e consultoria computacionalmente pesadas.
`MCPG_ELICIT_CONFIRM_WRITES`	`false`	Quando verdadeiro, cada chamada de ferramenta de gravação/DDL/shell/listen/migrate (qualquer ferramenta cuja anotação `readOnlyHint` não seja verdadeira) requer uma confirmação interativa aceita (`ctx.elicit()`) antes de executar. Melhor esforço, não um limite de aplicação: só engaja para clientes que passam um `context` de solicitação e declaram a capacidade `elicitation` durante `initialize` — um cliente que omite qualquer um dos dois silenciosamente ignora o portão e a ferramenta roda normalmente.

SQL em linguagem natural

MCPg auto-descobre cada provedor configurado do ambiente na inicialização — defina quantas chaves de fornecedor você tiver e cada uma se torna chamável. Dezenove provedores vêm embutidos. Três são de primeira parte (Anthropic, OpenAI, Gemini); os outros dezesseis falam a API compatível com OpenAI com endpoints predefinidos do fornecedor: DeepSeek, Qwen, OpenRouter, Perplexity, xAI (Grok), Groq, Mistral, Together, Fireworks, DeepInfra, Cerebras, Nebius, Hugging Face, GitHub Models, SambaNova, e Moonshot (Kimi). Cada embutido é plug-and-play — defina a variável de ambiente convencional de chave de API do fornecedor e ele é auto-descoberto — e qualquer outro fornecedor compatível com OpenAI ou servidor de modelo local (Ollama, vLLM, LM Studio) ainda é plugável somente através de configuração via MCPG_NL2SQL_CUSTOM_PROVIDERS. A lista embutida inteira é um registro declarativo em nl2sql.py, então adicionar um fornecedor ou atualizar um modelo padrão aposentado é uma mudança de dados de uma linha.

Quando MCPG_NL2SQL_PROVIDER não está definido, MCPg auto-escolhe o padrão em ordem de registro — anthropic → openai → gemini permanecem primeiro para que implantações existentes não sejam afetadas. translate_nl_to_sql aceita um argumento opcional provider="…" para rotear por chamada; get_server_info relata quais estão configurados.

Variável	Padrão	Descrição
`<VENDOR>_API_KEY`	—	Definir a chave convencional de um fornecedor habilita esse provedor. Slugs padrão: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, `PERPLEXITY_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, `TOGETHER_API_KEY`, `FIREWORKS_API_KEY`, `CEREBRAS_API_KEY`, `NEBIUS_API_KEY`, `SAMBANOVA_API_KEY`, `MOONSHOT_API_KEY`.
(chaves que desviam)	—	Alguns fornecedores não seguem `<VENDOR>_API_KEY`: Gemini → `GEMINI_API_KEY` ou `GOOGLE_API_KEY`; Qwen → `DASHSCOPE_API_KEY` ou `QWEN_API_KEY`; Hugging Face → `HF_TOKEN`; GitHub Models → `GITHUB_TOKEN`; DeepInfra → `DEEPINFRA_TOKEN`.
`MCPG_NL2SQL_PROVIDER`	auto-escolhido	Qualquer slug embutido (listado acima) ou um nome personalizado. Fixa o provedor padrão usado quando a ferramenta é chamada sem `provider=`. Não definido + qualquer chave de fornecedor presente → MCPg auto-escolhe em ordem de registro.
`MCPG_NL2SQL_API_KEY`	—	Chave explícita para o `MCPG_NL2SQL_PROVIDER` configurado. Substitui a variável de ambiente convencional do fornecedor somente para esse provedor. Requer `MCPG_NL2SQL_PROVIDER` definido.
`MCPG_NL2SQL_MODEL`	padrão do provedor	Substituir o modelo padrão (ex.: `claude-sonnet-4-6`, `gpt-4o-mini`, `grok-3-mini`). Aplica-se somente ao provedor padrão.
`MCPG_NL2SQL_BASE_URL`	—	Substituição de endpoint para o provedor padrão (gateways privados / endpoints regionais).
`MCPG_NL2SQL_CUSTOM_PROVIDERS`	—	Traga seu próprio provedor — sem mudança de código. Entradas `name=base_url\|model` separadas por vírgulas/nova linha declarando provedores extras compatíveis com OpenAI além dos embutidos (Ollama local / vLLM / LM Studio, ou qualquer fornecedor de nicho). Chave de `<NAME>_API_KEY` por convenção, ou anexe `\|KEY_ENV_VAR` para aqueles que desviam; sem chave permitido para endpoints de loopback. Cada nome se torna chamável via `provider=`.
`MCPG_NL2SQL_MAX_TOKENS`	`2048`	Limite em tokens gerados (limite rígido: 16384).

Exemplos de uso

As ferramentas MCP são invocadas pelo agente (Claude, Cursor, Continue, …) em resposta às suas instruções em linguagem natural. Algumas idas e voltas ilustrativas:

Inspecionar o esquema

Você: Quais tabelas vivem no esquema public, e quais são as maiores por contagem de linhas?

Agente (usando list_tables + summarize_table × N): Seis tabelas: customers (1,2M linhas), orders (4,7M), line_items (18,3M), products (340), addresses (1,4M), audit_log (45,8M — a maior, acumula sem retenção).

Diagnosticar uma consulta lenta

Você: Por que SELECT * FROM orders o JOIN line_items l ON o.id = l.order_id WHERE o.created_at > now() - interval '7 days' leva 8 segundos?

Agente (usando why_is_this_slow + recommend_indexes): EXPLAIN ANALYZE mostra uma varredura sequencial sobre orders (4,7M linhas) filtrada por created_at. Não há índice em orders.created_at. Recomendado: CREATE INDEX CONCURRENTLY orders_created_at_idx ON orders (created_at DESC); Melhoria esperada: ~95% de redução (varredura de índice toca ~33K linhas em vez da tabela inteira). Execute validate_migration nela antes de aplicar para confirmar que não há surpresa de lock.

Traduzir inglês simples para SQL

Você: Encontre clientes que fizeram um pedido este mês, mas nunca nos três meses anteriores — mostre-me o email deles e o gasto total atual ao longo da vida.

Agente (usando translate_nl_to_sql):

SELECT c.email, SUM(l.price * l.quantity) AS lifetime_spend
FROM customers c
JOIN orders o ON o.customer_id = c.id
JOIN line_items l ON l.order_id = o.id
WHERE EXISTS (
  SELECT 1 FROM orders o2 WHERE o2.customer_id = c.id
    AND o2.created_at >= date_trunc('month', now()))
  AND NOT EXISTS (
  SELECT 1 FROM orders o3 WHERE o3.customer_id = c.id
    AND o3.created_at >= date_trunc('month', now()) - interval '3 months'
    AND o3.created_at <  date_trunc('month', now()))
GROUP BY c.email;

Visualize o esquema

Você: Desenhe um diagrama ER do esquema public.

Agente (usando generate_schema_diagram): Retorna um diagrama Mermaid que você pode colar diretamente no GitHub / Notion / Obsidian.

Audite o banco de dados

Você: Quão saudável está este banco de dados agora?

Agente (usando audit_database): Retorna um relatório com nota: Memória e I/O 92 (BOM), Transações e Conexões 78 (AVISO: taxa de rollback 0,4%, veja os logs do aplicativo), Concorrência e Locks 60 (CRÍTICO: 14 backends aguardando), Limpeza e Bloat 88 (BOM), Consultas lentas 70 (AVISO: o template de consulta principal roda 5000×, média 90 ms — veja optimize_query).

Execute uma escrita protegida

Você: Soft-delete de todos os pedidos com mais de 5 anos.

Agente (usando run_write com MCPG_AUDIT_PERSIST=true): Valida a declaração através do kernel SafeSQL, executa-a dentro de uma transação, retorna o número de linhas afetadas, persiste a chamada (sql + argumentos — com segredos redigidos por regex — + status) em mcpg_audit.events para revisão posterior.

Para dezenas de outras receitas — roteamento multi-tenant, testes de RLS, NL→SQL, busca híbrida vetorial + FTS, Cypher do Apache AGE, TimescaleDB, exportação de esquemas ORM, cursores no lado do servidor — veja docs/cookbook.md.

O que está incluso

Lista compacta de categorias. Para a referência completa e atualizada de ferramentas, veja docs/tools.md; para um passo a passo guiado, veja docs/tour.md.

Introspecção de catálogo — schemas, tabelas, colunas, índices, constraints, views, funções, triggers, sequências, partições, políticas, papéis, grants, enums, domínios, tipos compostos, FDWs, publicações, assinaturas, extensões, colunas geradas.
Inteligência de consultas — run_select, run_select_parallel, explain_query, analyze_query_plan, why_is_this_slow, recommend_indexes, analyze_workload, check_database_health, detect_n_plus_one, audit_database.
Busca — fuzzy_search (trigrama), full_text_search, vector_search, hybrid_search (pgvector + FTS via RRF), geo_search (PostGIS k-NN).
Linguagem natural → SQL — translate_nl_to_sql (22 provedores integrados — Anthropic, OpenAI, Gemini, xAI, Groq, Mistral, Hugging Face, … — além de qualquer endpoint customizado compatível com OpenAI; a saída passa pelo mesmo kernel SafeSQL das consultas escritas à mão).
Visualização — generate_schema_diagram (ER), generate_fk_cascade_graph (raio de impacto de ON DELETE CASCADE), generate_graph_diagram (grafos de propriedades do Apache AGE).
Diff estrutural e migrações — compare_schemas, validate_migration, fluxo de trabalho em etapas prepare_migration / complete_migration / cancel_migration.
Apache AGE graph + Cypher — list_graphs, describe_graph, run_cypher, create_graph, drop_graph, generate_graph_diagram.
Ferramentas compostas e de consultoria — summarize_table, find_unused_objects, find_sensitive_columns (heurística de PII), lint_naming_conventions, test_rls_for_role, list_locks, find_blocking_chains, read_pg_stat_io (PG16+), generate_test_data.
Operações ao vivo e manutenção — list_active_queries, verify_connection_encryption (status TLS do link ativo), run_maintenance (VACUUM/ANALYZE), prune_audit_events (retenção de auditoria), cancel_query, terminate_backend, run_write, run_ddl, enable_extension.
Movimentação de dados — export_query / export_table (CSV/JSON), dump_database / restore_database, import_csv / import_json (COPY FROM STDIN), copy_table_between_databases.
Cursores no lado do servidor — open_cursor, fetch_cursor, close_cursor, list_cursors para leituras pagináveis sobre milhões de linhas.
TimescaleDB — list_hypertables, list_chunks, create_hypertable, add_compression_policy, add_retention_policy.
Exportadores de esquema ORM — Prisma, Drizzle, SQLAlchemy, sqlc, Diesel, jOOQ, Ent, Ecto.
Fluxos de eventos — subscribe_channel, poll_notifications, unsubscribe_channel, list_notification_subscriptions conectando PostgreSQL LISTEN/NOTIFY ao modelo de polling do MCP.
Observabilidade — endpoint Prometheus /metrics + ferramenta get_metrics_exposition para stdio; trilha de auditoria estruturada com redação de credenciais baseada em regex.

Documentação

docs/installation.md — instalação + configuração
docs/tour.md — tour guiado pelas ferramentas
docs/cookbook.md — receitas práticas para agentes
docs/tools.md — referência completa de ferramentas
docs/architecture.md — como as peças se encaixam
docs/scaling.md — dimensionamento de pool, réplicas, desempenho
docs/security-hardening.md — roteiro de funcionalidades de segurança
docs/release-process.md — como os lançamentos chegam ao PyPI
docs/adr/ — registros de decisões de arquitetura
Navegue em https://devopam.github.io/MCPg/

Segurança

Relato de vulnerabilidades: veja SECURITY.md. Janela de divulgação coordenada de 90 dias; relatos para devopam@gmail.com.
Defesa em profundidade: portões de capacidade, kernel SafeSQL, allowlist de identificadores, redação de auditoria, aplicação de TLS do PG na inicialização, limitação de taxa, validação de JWT OIDC, timeouts por sessão.
Veja docs/security-hardening.md para o roteiro vivo de itens de endurecimento entregues (✅) e na fila (⬜).

Política de Privacidade

MCPg é auto-hospedado: o conteúdo do seu banco de dados nunca sai da sua infraestrutura, e não há telemetria ou comunicação de qualquer tipo. A única exceção documentada é a ferramenta opcional translate_nl_to_sql, que envia sua pergunta mais o contexto do esquema (nomes, não dados de linhas) para o provedor de LLM que você configura. A política completa — coleta de dados, uso, armazenamento, compartilhamento com terceiros, retenção e contato — está em PRIVACY.md.

Notas de versão e changelog

Veja CHANGELOG.md para o histórico completo de versões, docs/release-process.md para como os lançamentos são feitos, e a página GitHub Releases para artefatos baixáveis.

Contribuindo

Pull requests são bem-vindos — veja CONTRIBUTING.md para a configuração do ciclo de desenvolvimento, convenções de teste e a lista de verificação de revisão por PR.

Licença

MIT — veja LICENSE. O kernel de segurança SQL (src/mcpg/sql/) é de primeira parte, reescrito a partir do crystaldba/postgres-mcp licenciado sob MIT; veja NOTICE para a linhagem.

Extensões empacotadas — licenças que você deve conhecer

O código-fonte do MCPg é MIT, mas as extensões PostgreSQL que ele empacota têm suas próprias licenças. Os wrappers estão à distância (chamadas em nível SQL, sem vinculação estática ou dinâmica ao processo Python do MCPg), então o projeto MCPg não é um trabalho derivado de nenhuma delas. Operadores que implantam um serviço construído sobre MCPg + uma extensão específica assumem quaisquer obrigações que a licença dessa extensão impõe — o mesmo que instalar a extensão diretamente. A matriz abaixo nomeia a licença por extensão empacotada para que você possa fazer uma escolha informada.

Extensão	Licença	Notas para operadores
pgvector	PostgreSQL License (estilo BSD)	Permissiva; sem obrigações especiais.
pg_partman	PostgreSQL License	Permissiva.
pg_cron	PostgreSQL License	Permissiva.
pg_turboquant	MIT	Permissiva.
pg_buffercache / pg_walinspect / pgstattuple	PostgreSQL contrib	Permissiva.
TimescaleDB	Apache 2.0 (comunidade) + Timescale License (TSL, código-fonte disponível) para alguns recursos	Mista — veja a documentação da Timescale para saber quais recursos são limitados pela TSL.
Apache AGE	Apache 2.0	Permissiva.
pg_search (ParadeDB)	AGPL-3.0	Operadores que executam um serviço de rede que permite aos usuários interagir com `pg_search` estão sujeitos à cláusula de rede da AGPL — tipicamente a obrigação de oferecer o código-fonte de `pg_search` (e quaisquer modificações) a esses usuários. Os wrappers do MCPg não estendem essa obrigação ao próprio MCPg; você assume a obrigação ao implantar e "transmitir" a extensão por uma rede. Se o seu modelo de redistribuição de serviço for incompatível com a cláusula de rede da AGPL, escolha uma implementação BM25 diferente (o plano BM25 lista alternativas).

Esta matriz é um ponto de partida — para a resposta vinculante sobre sua implantação específica, consulte o arquivo LICENSE upstream da extensão e (se for legalmente relevante) seu próprio advogado.

Aviso. Foram feitos os melhores esforços para levar o MCPg ao nível de produção, mas ele continua sendo um projeto em desenvolvimento ativo e pode conter problemas. Veja os termos da Licença para detalhes de indenização.

MCPg - Production-grade PostgreSQL MCP Server

Documentação

MCPg

📍 Listado em

Por que MCPg

Instalação

Do PyPI (recomendado)

Docker

Do código-fonte (desenvolvedores)

Início rápido

Instalação com um clique no Claude Desktop (.mcpb)

Ou configure manualmente (transporte stdio)

Sem dados interessantes ainda? Semeie o conjunto de dados de demonstração

Execute como servidor HTTP (para integrações de IDE, aplicativos web, etc.)

Configuração

Cenários comuns

Referência completa

Núcleo

Portas de capacidade (opt-in para ferramentas de maior raio de impacto)

Autenticação (somente transportes HTTP)

Endurecimento HTTP (somente transportes HTTP)

Multi-inquilinos (SET ROLE)

Réplicas de leitura

Múltiplos bancos de dados (secundários somente leitura)

Pool / timeouts / TLS

Ferramentas de subprocesso (somente MCPG_ALLOW_SHELL=true)

LISTEN/NOTIFY (somente MCPG_ALLOW_LISTEN=true)

Auditoria

Backend de segredos

Limitação de taxa

Cache e flags de recursos

SQL em linguagem natural

Exemplos de uso

Inspecionar o esquema

Diagnosticar uma consulta lenta

Traduzir inglês simples para SQL

Visualize o esquema

Audite o banco de dados

Execute uma escrita protegida

O que está incluso

Documentação

Segurança

Política de Privacidade

Notas de versão e changelog

Contribuindo

Licença

Extensões empacotadas — licenças que você deve conhecer

Multi-inquilinos (`SET ROLE`)

Ferramentas de subprocesso (somente `MCPG_ALLOW_SHELL=true`)

LISTEN/NOTIFY (somente `MCPG_ALLOW_LISTEN=true`)