postgres-control-bridge

Servidor MCP (Model Context Protocol) para integração com PostgreSQL, permitindo que IAs executem consultas seguras em bancos de dados PostgreSQL através de ferramentas estruturadas.

Instalação

npm install -g postgres-control-bridge

Ou instale localmente no seu projeto:

npm install postgres-control-bridge

Uso via npx (sem instalação)

Você também pode usar diretamente via npx sem instalar:

npx postgres-control-bridge

Nota: Na primeira execução, o npx baixará o pacote temporariamente. Para uso contínuo, recomenda-se a instalação global ou local.

Funcionalidades

Consultas e Análise

• Consultas SELECT seguras - Execute apenas consultas de leitura e CTEs (WITH)
• Análise de queries - Explique planos de execução com EXPLAIN e EXPLAIN ANALYZE

Explorar Banco de Dados

• Listagem de schemas - Visualize todos os schemas disponíveis
• Listagem de tabelas - Visualize todas as tabelas do banco por schema
• Descrição de tabelas - Obtenha estrutura detalhada das tabelas com constraints

Conexão

• Conexão direta - Conecte-se diretamente ao PostgreSQL
• Múltiplos hosts - Suporte a conexões simultâneas com múltiplos servidores PostgreSQL
• Configuração flexível - Suporte a múltiplos ambientes e interpolação de variáveis
• Suporte a SSL - Conecte a bancos PostgreSQL com SSL

Segurança

• Somente SELECTs e CTEs - Apenas consultas de leitura são permitidas
• Limite de resultados - Máximo de 1000 registros por consulta
• Validação de queries - Verificação automática de comandos perigosos
• Schemas isolados - Acesso controlado por schema quando necessário

Configuração

Variáveis de Ambiente Obrigatórias

POSTGRES_HOST=localhost
POSTGRES_USER=seu_usuario
POSTGRES_DATABASE=sua_base_dados

Variáveis de Ambiente Opcionais

POSTGRES_PORT=5432                # Padrão: 5432
POSTGRES_PASSWORD=sua_senha       # Padrão: string vazia
POSTGRES_SSL=true                 # Padrão: false (usar SSL)

Suporte a Múltiplos Hosts

O PostgreSQL Control Bridge agora suporta conexões simultâneas com múltiplos servidores PostgreSQL. Cada host é identificado por um nome único e pode ter suas próprias credenciais.

Formato de configuração:

As credenciais podem ser configuradas de três formas:

Opção 1: Variável POSTGRES_HOSTS (JSON)

Configure múltiplos hosts usando uma variável JSON:

{
  "modelcontextprotocol": {
    "servers": {
      "postgres": {
        "command": "postgres-control-bridge",
        "env": {
          "POSTGRES_HOSTS": "{\"prod\":{\"POSTGRES_HOST\":\"prod.example.com\",\"POSTGRES_USER\":\"user\",\"POSTGRES_PASSWORD\":\"pass\",\"POSTGRES_DATABASE\":\"db\",\"POSTGRES_SSL\":\"true\"},\"dev\":{\"POSTGRES_HOST\":\"dev.example.com\",\"POSTGRES_USER\":\"dev_user\",\"POSTGRES_PASSWORD\":\"dev_pass\",\"POSTGRES_DATABASE\":\"dev_db\",\"POSTGRES_SSL\":\"false\"}}"
        }
      }
    }
  }
}

Opção 2: Padrão de prefixo (HOSTNAME_*)

Configure hosts usando variáveis com prefixo:

{
  "modelcontextprotocol": {
    "servers": {
      "postgres": {
        "command": "postgres-control-bridge",
        "env": {
          "PROD_POSTGRES_HOST": "prod.example.com",
          "PROD_POSTGRES_USER": "user",
          "PROD_POSTGRES_PASSWORD": "pass",
          "PROD_POSTGRES_DATABASE": "db",
          "PROD_POSTGRES_SSL": "true",
          "DEV_POSTGRES_HOST": "dev.example.com",
          "DEV_POSTGRES_USER": "dev_user",
          "DEV_POSTGRES_PASSWORD": "dev_pass",
          "DEV_POSTGRES_DATABASE": "dev_db",
          "DEV_POSTGRES_SSL": "false"
        }
      }
    }
  }
}

Opção 3: Modo compatibilidade (host único)

Para manter compatibilidade com versões anteriores, se apenas variáveis diretas forem configuradas (sem POSTGRES_HOSTS ou prefixos), o sistema criará automaticamente um host chamado "default":

{
  "modelcontextprotocol": {
    "servers": {
      "postgres": {
        "command": "postgres-control-bridge",
        "env": {
          "POSTGRES_HOST": "localhost",
          "POSTGRES_USER": "user",
          "POSTGRES_PASSWORD": "pass",
          "POSTGRES_DATABASE": "db",
          "POSTGRES_SSL": "false"
        }
      }
    }
  }
}

Uso nas ferramentas:

Todas as ferramentas agora aceitam um parâmetro opcional host para especificar qual servidor usar:

{
  "host": "prod",
  "query": "SELECT * FROM usuarios LIMIT 10"
}

Se apenas um host estiver configurado, o parâmetro host pode ser omitido. Se múltiplos hosts estiverem configurados, o parâmetro host é obrigatório.

Gerenciamento de conexões:

• Cada host mantém sua própria conexão PostgreSQL
• Conexões são reutilizadas automaticamente quando possível
• Conexões expiradas são detectadas e reconectadas automaticamente
• Todas as conexões são fechadas adequadamente no shutdown

Configuração das Variáveis de Ambiente

O PostgreSQL Control Bridge suporta um sistema flexível de configuração com múltiplos níveis de fallback e suporte a interpolação de variáveis:

Ordem de Prioridade (da mais alta para mais baixa):

1. Variáveis diretas no .cursor/settings.json (mais alta prioridade) ✅

   • Valores explícitos como "POSTGRES_HOST": "localhost" têm prioridade máxima
   • Variáveis com interpolação como "POSTGRES_HOST": "${DB_HOST}" são resolvidas usando os fallbacks abaixo

2. Arquivo .cursor/.env (fallback médio) ✅

   • Usado para resolver interpolações ou valores não definidos no settings.json
   • Sobrescreve valores do .env da raiz

3. Arquivo .env na raiz do projeto (fallback mais baixo) ✅

   • Base genérica para todo o projeto
   • Usado como último fallback para interpolações

4. Variáveis do sistema (process.env já existentes)

Arquivos .env

Você pode criar arquivos .env em até dois locais:

.env na raiz do projeto (base)

DB_HOST=localhost
DB_PORT=5432
DB_USER=seu_usuario
DB_PASSWORD=sua_senha
DB_NAME=sua_base_dados

.cursor/.env (opcional, sobrescreve valores da raiz)

DB_PASSWORD=senha_diferente_para_desenvolvimento

O servidor carrega automaticamente esses arquivos na ordem correta:

1. Primeiro carrega .env da raiz (fallback baixo)
2. Depois carrega .cursor/.env (sobrescreve raiz, mas não valores do settings.json)
3. Valores diretos no settings.json sempre têm prioridade e nunca são sobrescritos

Interpolação de Variáveis no .cursor/settings.json

Você pode usar interpolação de variáveis no campo env do settings.json:

• ${VAR} - Referencia uma variável de ambiente
• ${VAR:-default} - Usa um valor padrão se a variável não existir

Isso permite referenciar variáveis definidas nos arquivos .env ou outras variáveis de ambiente.

Exemplo com interpolação:

{
  "modelcontextprotocol": {
    "servers": {
      "postgres": {
        "command": "postgres-control-bridge",
        "env": {
          "POSTGRES_HOST": "${DB_HOST}",
          "POSTGRES_PORT": "${DB_PORT:-5432}",
          "POSTGRES_USER": "${DB_USER}",
          "POSTGRES_PASSWORD": "${DB_PASSWORD}",
          "POSTGRES_DATABASE": "${DB_NAME}",
          "POSTGRES_SSL": "${DB_SSL:-false}"
        }
      }
    }
  }
}

Exemplo prático da ordem de prioridade:

Se você tiver:

.cursor/settings.json:

"POSTGRES_HOST": "${DB_HOST}"

.cursor/.env:

DB_HOST=dev.example.com

.env (raiz):

DB_HOST=localhost

Resultado: POSTGRES_HOST será dev.example.com (usa .cursor/.env, que tem prioridade sobre raiz)

Se você tiver:

.cursor/settings.json:

"POSTGRES_HOST": "prod.example.com"  // valor direto

.cursor/.env:

POSTGRES_HOST=dev.example.com

Resultado: POSTGRES_HOST será prod.example.com (valores diretos no JSON sempre ganham)

Importante: Lembre-se de adicionar .env e .cursor/.env ao .gitignore para não versionar credenciais!

Configuração no Cursor IDE (por workspace)

Crie o arquivo .cursor/settings.json na raiz do seu workspace com o conteúdo abaixo. Essa configuração fica versionada no projeto, vale apenas para esse workspace e não interfere em outros.

Se instalado globalmente:

{
  "modelcontextprotocol": {
    "servers": {
      "postgres": {
        "command": "postgres-control-bridge",
        "env": {
          "POSTGRES_HOST": "localhost",
          "POSTGRES_PORT": "5432",
          "POSTGRES_USER": "seu_usuario",
          "POSTGRES_PASSWORD": "sua_senha",
          "POSTGRES_DATABASE": "sua_base_dados",
          "POSTGRES_SSL": "false"
        }
      }
    }
  }
}

Se instalado localmente no projeto:

{
  "modelcontextprotocol": {
    "servers": {
      "postgres": {
        "command": "node",
        "args": ["./node_modules/postgres-control-bridge/server.js"],
        "env": {
          "POSTGRES_HOST": "localhost",
          "POSTGRES_PORT": "5432",
          "POSTGRES_USER": "seu_usuario",
          "POSTGRES_PASSWORD": "sua_senha",
          "POSTGRES_DATABASE": "sua_base_dados",
          "POSTGRES_SSL": "false"
        }
      }
    }
  }
}

Usando via npx (sem instalação):

{
  "modelcontextprotocol": {
    "servers": {
      "postgres": {
        "command": "npx",
        "args": ["postgres-control-bridge"],
        "env": {
          "POSTGRES_HOST": "localhost",
          "POSTGRES_PORT": "5432",
          "POSTGRES_USER": "seu_usuario",
          "POSTGRES_PASSWORD": "sua_senha",
          "POSTGRES_DATABASE": "sua_base_dados",
          "POSTGRES_SSL": "false"
        }
      }
    }
  }
}

Exemplo com múltiplos ambientes usando interpolação:

.cursor/settings.json:

{
  "modelcontextprotocol": {
    "servers": {
      "postgres-dev": {
        "command": "postgres-control-bridge",
        "env": {
          "POSTGRES_HOST": "${DB_HOST_DEV:-localhost}",
          "POSTGRES_USER": "${DB_USER_DEV}",
          "POSTGRES_PASSWORD": "${DB_PASSWORD_DEV}",
          "POSTGRES_DATABASE": "${DB_NAME_DEV}",
          "POSTGRES_SSL": "false"
        }
      },
      "postgres-prod": {
        "command": "postgres-control-bridge",
        "env": {
          "POSTGRES_HOST": "${DB_HOST_PROD}",
          "POSTGRES_USER": "${DB_USER_PROD}",
          "POSTGRES_PASSWORD": "${DB_PASSWORD_PROD}",
          "POSTGRES_DATABASE": "${DB_NAME_PROD}",
          "POSTGRES_SSL": "true"
        }
      }
    }
  }
}

.cursor/.env (valores específicos do workspace):

DB_HOST_DEV=localhost
DB_USER_DEV=dev_user
DB_PASSWORD_DEV=dev_pass
DB_NAME_DEV=development_db

DB_HOST_PROD=prod.example.com
DB_USER_PROD=prod_user
DB_PASSWORD_PROD=prod_pass
DB_NAME_PROD=production_db

Por que usar .cursor/settings.json?

• Mais flexível: a configuração vive junto do projeto e pode variar por workspace.
• Versionável: pode ser commitada e compartilhada com a equipe via Git (sem credenciais).
• Isolado por projeto: não afeta outras pastas ou instalações do Cursor.
• Fácil trocar de ambiente: crie entradas como postgres-dev, postgres-hml e postgres-prod no mesmo arquivo.
• Suporte a interpolação: use ${VAR} para referenciar variáveis dos arquivos .env.
• Sem tocar no sistema: dispensa editar arquivos globais do Cursor.

Ferramentas Disponíveis

1. execute_select_query

Executa queries SELECT e CTEs (WITH) com segurança.

Parâmetros:

• host (string, opcional): Nome do host a usar (obrigatório se múltiplos hosts estiverem configurados)
• query (string, obrigatório): Query SELECT ou WITH para executar
• limit (number, opcional): Limite de resultados (máximo 1000, padrão 100)

Exemplos:

SELECT * FROM usuarios WHERE ativo = true;

WITH vendas_mensais AS (
  SELECT DATE_TRUNC('month', data_venda) as mes, SUM(valor) as total
  FROM vendas
  WHERE data_venda >= '2024-01-01'
  GROUP BY DATE_TRUNC('month', data_venda)
)
SELECT * FROM vendas_mensais ORDER BY mes;

2. describe_table

Mostra a estrutura detalhada de uma tabela incluindo constraints.

Parâmetros:

• host (string, opcional): Nome do host a usar (obrigatório se múltiplos hosts estiverem configurados)
• tableName (string, obrigatório): Nome da tabela
• schemaName (string, opcional): Nome do schema (padrão: public)

Exemplo:

tableName: usuarios
schemaName: public

3. explain_query

Analisa o plano de execução de uma query.

Parâmetros:

• host (string, opcional): Nome do host a usar (obrigatório se múltiplos hosts estiverem configurados)
• query (string, obrigatório): Query para analisar
• analyze (boolean, opcional): Usar EXPLAIN ANALYZE para análise mais detalhada (padrão: false)

Exemplos:

SELECT * FROM pedidos p JOIN usuarios u ON p.usuario_id = u.id WHERE u.cidade = 'São Paulo';

4. list_tables

Lista todas as tabelas do banco de dados.

Parâmetros:

• host (string, opcional): Nome do host a usar (obrigatório se múltiplos hosts estiverem configurados)
• schemaName (string, opcional): Nome do schema para filtrar

Exemplo:

host: dev
schemaName: public

5. list_schemas

Lista todos os schemas do banco de dados.

Parâmetros:

• host (string, opcional): Nome do host a usar (obrigatório se múltiplos hosts estiverem configurados)

Exemplos de Uso no Cursor

Após configurar o servidor, você pode usar comandos como:

"Liste todos os schemas do banco"
"Liste todas as tabelas do schema public no host dev"
"Mostre a estrutura da tabela usuarios no host prod"
"Execute no dev: SELECT COUNT(*) FROM pedidos WHERE created_at >= '2024-01-01'"
"Explique esta query no prod: SELECT * FROM produtos WHERE preco > 100"
"Analyze query no dev: SELECT p.*, u.nome FROM pedidos p JOIN usuarios u ON p.usuario_id = u.id"

Recursos Específicos do PostgreSQL

Suporte a CTEs (Common Table Expressions)

WITH RECURSIVE categorias_hierarquia AS (
  SELECT id, nome, parent_id, 1 as nivel
  FROM categorias WHERE parent_id IS NULL
  UNION ALL
  SELECT c.id, c.nome, c.parent_id, ch.nivel + 1
  FROM categorias c
  JOIN categorias_hierarquia ch ON c.parent_id = ch.id
)
SELECT * FROM categorias_hierarquia ORDER BY nivel, nome;

Funções de Janela (Window Functions)

SELECT
  nome,
  salario,
  RANK() OVER (ORDER BY salario DESC) as ranking,
  AVG(salario) OVER () as media_geral
FROM funcionarios;

Arrays e JSONB

SELECT
  id,
  tags,
  metadata->>'tipo' as tipo,
  jsonb_array_length(dados->'itens') as qtd_itens
FROM produtos
WHERE 'eletrônico' = ANY(tags);

Segurança

• Somente SELECTs e CTEs: Apenas consultas de leitura são permitidas
• Limite de resultados: Máximo de 1000 registros por consulta
• Validação de queries: Verificação automática de comandos perigosos
• Suporte a SSL: Conexões criptografadas para ambientes de produção
• Schemas isolados: Acesso controlado por schema quando necessário

Solução de Problemas

Erro de Conexão

❌ Erro ao conectar ao PostgreSQL: connect ECONNREFUSED

Solução: Verifique se o PostgreSQL está rodando e as credenciais estão corretas.

Variáveis de Ambiente Faltando

❌ Variáveis de ambiente faltando: POSTGRES_HOST, POSTGRES_USER

Solução: Configure todas as variáveis obrigatórias.

Erro de SSL

❌ SSL connection required

Solução: Configure POSTGRES_SSL=true ou ajuste as configurações SSL do servidor.

Permissões Insuficientes

❌ permission denied for table

Solução: Verifique as permissões do usuário PostgreSQL no schema/tabela.

Schema não encontrado

❌ schema "nome_schema" does not exist

Solução: Verifique se o schema existe usando a ferramenta list_schemas.

Host não encontrado

❌ Parâmetro 'host' é obrigatório. Hosts disponíveis: PROD, DEV

Solução: Se você configurou múltiplos hosts, especifique o parâmetro host nas chamadas das ferramentas. Use os nomes dos hosts listados na mensagem de erro.

Host não encontrado (nome específico)

❌ Host 'nome_do_host' não encontrado. Hosts disponíveis: DEV, PROD

Solução: Verifique se o nome do host está correto. O sistema é case-insensitive, mas use o mesmo formato configurado. Verifique a configuração de hosts em POSTGRES_HOSTS ou variáveis com prefixo.

Diferenças do MySQL

• Schemas: PostgreSQL usa schemas para organizar tabelas (padrão: public)
• Tipos de dados: Suporte a arrays, JSONB, UUID, etc.
• CTEs recursivas: Suporte nativo a consultas recursivas
• Case-sensitive: Nomes não-quoted são convertidos para minúsculas
• Funções de janela: Suporte avançado a window functions
• EXPLAIN ANALYZE: Análise de performance mais detalhada

Requisitos

• Node.js >= 14.0.0
• PostgreSQL >= 12
• Cursor IDE com suporte a MCP (ou outro cliente MCP compatível)

Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request

Licença

ISC License - Veja o arquivo LICENSE para mais detalhes.

Autor

Nicolas Costa

Links

• GitHub Repository
• npm Package
• Report Issues