helderto/postgres-mcp-free repository overview

⁠PostgreSQL MCP Server - Free Edition

Um servidor MCP (Model Context Protocol) para PostgreSQL com liberdade total - permite executar qualquer comando SQL, incluindo CREATE DATABASE, DROP DATABASE, e outras operações que normalmente requerem autocommit.

⁠Características

• 30 ferramentas disponíveis para IA
• Autocommit habilitado - executa qualquer comando SQL
• Sem restrições de transação - CREATE/DROP DATABASE funcionam
• Baseado em Debian 13 (Trixie)
• Seguro - roda com usuário não-root

⁠Ferramentas Disponíveis

⁠SQL Geral

⁠Databases

⁠Tabelas

⁠Roles e Usuários

⁠Permissões

⁠Monitoramento

⁠Schemas

⁠Índices e Performance

⁠Backup e Export

⁠Instalação

⁠Via Docker Hub

docker pull seuusuario/postgres-mcp-free:latest

⁠Build Local

git clone https://github.com/seuusuario/postgres-mcp-free.git
cd postgres-mcp-free
docker build -t postgres-mcp-free .

⁠Uso

⁠Com Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "postgres-free": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URI",
        "seuusuario/postgres-mcp-free:latest"
      ],
      "env": {
        "DATABASE_URI": "postgresql://usuario:[email protected]:5432/banco"
      }
    }
  }
}

⁠Com Claude Code

Crie um arquivo .mcp.json no seu projeto:

{
  "mcpServers": {
    "postgres-free": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URI",
        "seuusuario/postgres-mcp-free:latest"
      ],
      "env": {
        "DATABASE_URI": "postgresql://usuario:[email protected]:5432/banco"
      }
    }
  }
}

⁠Com Docker Compose (desenvolvimento)

docker-compose up -d

Isso irá subir um PostgreSQL e o MCP Server conectado.

⁠Configuração

⁠Variáveis de Ambiente

⁠Formato da Connection String

postgresql://usuario:senha@host:porta/banco

Importante para Docker:

• No Windows/Mac: use host.docker.internal para acessar o host
• No Linux: use 172.17.0.1 ou o IP do host

⁠Como conectar rapidamente

• Windows/Mac (Docker Desktop): postgresql://postgres:[email protected]:5432/postgres
• Linux: postgresql://postgres:[email protected]:5432/postgres (ou o IP do host)
• Ajuste usuário/senha/banco conforme seu ambiente e passe em DATABASE_URI.
• No compose incluso, o serviço Postgres interno é acessível pelo host postgres na rede mcp-network.

⁠Exemplos de Uso

⁠Criar um Database

IA: Crie um database chamado "meu_app"

⁠Criar um Usuário com Permissões

IA: Crie um usuário "app_user" com senha "123456" e dê permissão de SELECT e INSERT na tabela "usuarios"

⁠Monitorar Conexões

IA: Liste todas as conexões ativas no banco

⁠Analisar Performance

IA: Mostre as estatísticas da tabela "pedidos" e sugira índices

⁠Segurança

⚠️ ATENÇÃO: NÃO USE EM PRODUÇÃO. Este MCP Server tem acesso total ao PostgreSQL, com autocommit habilitado e sem bloqueios para comandos destrutivos. Destinado a desenvolvimento/lab.

Recomendações:

• Restrinja o uso a ambientes de desenvolvimento/lab
• Não exponha publicamente sem autenticação forte
• Use roles de mínimo privilégio e credenciais descartáveis
• Mantenha backups regulares mesmo em dev

⁠Desenvolvimento

⁠Requisitos

• Python 3.10+
• Docker (opcional)

⁠Instalação Local

pip install mcp psycopg2-binary
export DATABASE_URI='postgresql://postgres:senha@localhost:5432/postgres'
python server.py

⁠Descrição curta (para Docker Hub)

Servidor MCP para PostgreSQL com autocommit liberado (CREATE/DROP DB, GRANT/REVOKE, VACUUM, COPY CSV). Feito para desenvolvimento/lab; desencorajado para produção.

⁠Estrutura do Projeto

postgres-mcp-free/
├── server.py           # Servidor MCP
├── requirements.txt    # Dependências Python
├── Dockerfile          # Imagem Docker
├── docker-compose.yml  # Compose para dev
├── .dockerignore       # Arquivos ignorados no build
└── README.md           # Esta documentação

⁠Contribuindo

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -m 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

⁠Licença

MIT License - veja LICENSE⁠ para detalhes.

⁠Autor

Renan Goulart

Links:

• MCP Protocol⁠
• PostgreSQL⁠
• Docker Hub⁠