mcp-postgres-secure

MCP PostgreSQL Secure

Um servidor Model Context Protocol para PostgreSQL com modos de acesso baseados em permissões. Escolha quanta potência de banco de dados a IA recebe no momento da instalação.

Modos de acesso

Modo	PG_ACCESS_MODE	Ferramentas	SQL permitido
Somente leitura	readonly (padrão)	query, introspecção de esquema	SELECT, WITH, EXPLAIN, SHOW, etc.
Leitura + DML	dml	acima + execute	DML: INSERT, UPDATE, DELETE, MERGE
Acesso total	full	acima + execute (DDL)	DML + DDL: CREATE, ALTER, DROP, TRUNCATE, etc.

Defesa em profundidade:

• Classificação de SQL em nível de aplicação (bloqueia consultas de múltiplas instruções e tipos de instrução não permitidos)
• Sessão PostgreSQL default_transaction_read_only = on no modo readonly
• Bloqueio de conexão via PG_LOCK_CONNECTION para que as credenciais não possam ser trocadas em tempo de execução ao usar configuração por env

Combine cada modo com um papel PostgreSQL que tenha concessões correspondentes. O servidor impõe a intenção; o usuário do banco de dados é a autoridade final.

Instalação

A partir do npm

npm install mcp-postgres-secure

Ou execute diretamente:

npx mcp-postgres-secure --access-mode readonly

A partir do código-fonte (fork)

git clone https://github.com/pugltd/mcp-postgres-secure.git
cd mcp-postgres-secure
npm install
npm run build

Aponte o Cursor para node /absolute/path/to/mcp-postgres-secure/build/index.js.

Configuração

Todos os modos usam as mesmas variáveis de ambiente de conexão. Defina o nível de acesso com --access-mode (CLI) ou PG_ACCESS_MODE (env). A flag da CLI vence se ambas forem definidas.

Variável / flag	Obrigatório	Padrão	Descrição
--access-mode	não	readonly	readonly, dml ou full (substitui env)
PG_ACCESS_MODE	não	readonly	O mesmo que --access-mode
PG_HOST	sim	—	Host do banco de dados
PG_PORT	não	5432	Porta do banco de dados
PG_USER	sim	—	Usuário do banco de dados
PG_PASSWORD	sim	—	Senha do banco de dados
PG_DATABASE	sim	—	Nome do banco de dados
PG_LOCK_CONNECTION	não	true quando a configuração por env está definida	Desabilita connect_db em tempo de execução

# CLI examples
npx mcp-postgres-secure --access-mode readonly
npx mcp-postgres-secure --access-mode=dml
node build/index.js --help

1. Somente leitura (padrão recomendado)

Use para explorar esquemas e executar análises sem risco de escrita.

{
  "mcpServers": {
    "postgres-readonly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-postgres-secure", "--access-mode", "readonly"],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "mcp_readonly",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "your_database",
        "PG_LOCK_CONNECTION": "true"
      }
    }
  }
}

2. Leitura + DML

Use quando a IA puder inserir, atualizar ou excluir linhas, mas não puder alterar o esquema.

{
  "mcpServers": {
    "postgres-dml": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-postgres-secure", "--access-mode", "dml"],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "mcp_dml",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "your_database",
        "PG_LOCK_CONNECTION": "true"
      }
    }
  }
}

3. Acesso total (DDL)

Use apenas quando alterações de esquema forem necessárias. Prefira um papel de administrador dedicado com privilégios baixos, não um superusuário.

{
  "mcpServers": {
    "postgres-full": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-postgres-secure", "--access-mode", "full"],
      "env": {
        "PG_HOST": "localhost",
        "PG_PORT": "5432",
        "PG_USER": "mcp_admin",
        "PG_PASSWORD": "your_password",
        "PG_DATABASE": "your_database",
        "PG_LOCK_CONNECTION": "true"
      }
    }
  }
}

Você pode registrar várias entradas MCP (por exemplo, postgres-readonly e postgres-dml) e habilitar apenas a que precisar por projeto.

Ferramentas disponíveis

query

SQL somente leitura. Suporta placeholders estilo PostgreSQL ($1, $2) e estilo MySQL (?).

use_mcp_tool({
  server_name: "postgres-readonly",
  tool_name: "query",
  arguments: {
    sql: "SELECT * FROM users WHERE id = $1",
    params: [1]
  }
});

execute (somente modos dml e full)

SQL de mutação. No modo dml: apenas INSERT, UPDATE, DELETE, MERGE. No modo full: DML e DDL.

use_mcp_tool({
  server_name: "postgres-dml",
  tool_name: "execute",
  arguments: {
    sql: "UPDATE users SET active = $1 WHERE id = $2",
    params: [true, 1]
  }
});

list_schemas, list_tables, describe_table

Introspecção de esquema (todos os modos).

connect_db

Conexão opcional em tempo de execução quando PG_LOCK_CONNECTION=false e variáveis de ambiente não estão definidas. Desabilitada por padrão ao usar configuração baseada em env.

Exemplos de papéis PostgreSQL

Usuário somente leitura:

CREATE ROLE mcp_readonly LOGIN PASSWORD '...';
GRANT CONNECT ON DATABASE your_database TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

Usuário DML (adicionar concessões de escrita, sem DDL):

CREATE ROLE mcp_dml LOGIN PASSWORD '...';
-- same as above, plus:
GRANT INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO mcp_dml;

Usuário administrador (migrações / DDL): conceda apenas nos esquemas que a IA deve gerenciar.

Segurança

• Consultas parametrizadas para valores fornecidos pelo usuário
• Execução de instrução única (sem lotes encadeados por ;)
• Validação do tipo de instrução por modo de acesso
• Transações PostgreSQL somente leitura no modo readonly
• connect_db em tempo de execução desabilitado quando a conexão está bloqueada por env
• Credenciais via variáveis de ambiente (não argumentos de chat)

Limitações: a validação é baseada em palavras-chave, não é um parser SQL completo. Use papéis de banco de dados com privilégios mínimos e bancos de dados não produtivos quando possível.

Tratamento de erros

O servidor retorna erros claros para:

• SQL inválido ou não permitido para o modo de acesso atual
• Múltiplas instruções em uma única solicitação
• Falhas de conexão
• Parâmetros ausentes
• Ferramentas desabilitadas (execute no modo readonly, connect_db quando bloqueado)

Licença

MIT

Upstream

Bifurcado de antonorlov/mcp-postgres-server.