Omni-Image-Tools MCP

Um servidor MCP que dá visão computacional para modelos de IA. Ele permite que a IA "veja" imagens: descrever, comparar, extrair texto, recortar objetos e muito mais.

11 ferramentas · 4 provedores · Funciona com Opencode, Claude, Cursor

🤔 Qual provedor usar?

Se você tem GPU (placa de vídeo) → Ollama

O modelo roda no seu computador, usando sua placa de vídeo. Grátis, privado, sem depender de internet.

Limite: sua GPU tem memória finita — por isso só 1 imagem por vez e modelos menores.

Se você não tem GPU ou quer mais qualidade → Nuvem

O modelo roda na nuvem (OpenAI, OpenRouter). Pago por uso, precisa de API key, sem limites de imagem.

Escolha seu modelo

⚠️ Memória importa: Se você tem 4GB de VRAM, use qwen3-vl:2b. Com 6GB+, pode usar qwen3-vl:4b. Os modelos de nuvem não usam sua GPU.

🚀 Início Rápido

# 1. Baixar e instalar (requer uv: https://docs.astral.sh/uv/)
git clone https://github.com/alexlivre/omni-image-tools-mcp
cd omni-image-tools-mcp
uv sync
uv sync --extra dev

# 2. Se for usar Ollama (grátis, local):
set OMNI_VISION_PROVIDER=ollama
set OMNI_VISION_DEFAULT_MODEL=qwen3-vl:2b

# 3. Testar
uv run python scripts/cli.py analyze --image foto.jpg --prompt "O que tem nesta imagem?"

💡 Dica: Se quiser usar nuvem, veja a seção Como configurar cada provedor mais abaixo.

🧰 Ferramentas

👁️ Visão (usam inteligência artificial)

Por que o Ollama tem limite de 1 imagem? Porque a memória da GPU é limitada. Enviar várias imagens de uma vez pode estourar a memória e travar tudo. O sistema automaticamente gerencia isso — na nuvem não tem esse problema.

🛠️ Processamento (não usam IA, são rápidas)

⚙️ Sistema

🌟 Ferramenta Destaque: extract_object

Essa ferramenta é inteligente: você diz o que quer recortar e ela acha sozinha.

uv run python scripts/cli.py extract --image carro.jpg --object "license plate"

O que acontece por dentro:

1. A IA localiza o objeto na imagem → coordenadas
2. O sistema recorta automaticamente a região
3. Salva o recorte em outputs/ (ou o diretório definido por OMNI_OUTPUT_DIR)

Útil para: placas de carro, rostos, logotipos, textos específicos, qualquer objeto visível.

⚙️ Como configurar cada provedor

Opção A: Ollama (gratuito, local)

Requer: Ollama instalado e o modelo baixado (ollama pull qwen3-vl:2b)

set OMNI_VISION_PROVIDER=ollama
set OMNI_VISION_DEFAULT_MODEL=qwen3-vl:2b

Opção B: OpenAI (nuvem, pago)

Requer: API key da OpenAI

set OMNI_VISION_PROVIDER=openai
set OMNI_VISION_API_KEY=sk-proj-sua-chave-aqui
set OMNI_VISION_DEFAULT_MODEL=gpt-5.4-mini

Opção C: OpenRouter (nuvem, barato)

Requer: API key do OpenRouter

set OMNI_VISION_PROVIDER=openrouter
set OMNI_VISION_API_KEY=sk-or-v1-sua-chave-aqui
set OMNI_VISION_DEFAULT_MODEL=qwen/qwen3-vl-32b-instruct

Opção D: MiniMax (nuvem, MiniMax-M3 multimodal)

Requer: API key da MiniMax. Suporta as duas plataformas:

• Internacional (minimax.io) — padrão, sem config extra
• China (minimaxi.com) — defina MINIMAX_BASE_URL=https://api.minimaxi.com/v1

# Internacional (padrão)
set OMNI_VISION_PROVIDER=minimax
set MINIMAX_API_KEY=sua-chave-aqui

# China (opcional)
set MINIMAX_BASE_URL=https://api.minimaxi.com/v1

💡 A chave pode vir de OMNI_VISION_API_KEY ou MINIMAX_API_KEY (esta última é usada como fallback, útil se já estiver nas variáveis de ambiente do sistema).

Todas as opções

🔒 Segurança embutida

• SSRF: download_image bloqueia IPs privados/loopback/link-local (ex.: 169.254.169.254), hosts que resolvam para eles, e revalida cada redirect.
• Path traversal: todos os image_path são resolvidos (resolve() segue symlinks); com OMNI_ALLOWED_DIRS configurado, caminhos fora do sandbox são rejeitados.
• Downloads limitados: download é em streaming com teto de 20 MB (Content-Length + contador de bytes).
• Privacidade: get_image_info retorna EXIF desligado por padrão (include_exif); se ativado e houver GPS, um aviso é adicionado.

🔌 Integração com Opencode

Nota: o servidor agora roda sobre o FastMCP, o que adiciona relatório de progresso e timeouts por ferramenta. O console script omni-image-tools usa o novo entry point src.server_fastmcp:main. O antigo src/server.py permanece como fallback (python -m src.server) por uma release (é ele que emite structuredContent/outputSchema).

Adicione no arquivo ~/.config/opencode/opencode.json:

{
  "mcp": {
    "omni-image-tools": {
      "type": "local",
      "command": ["C:\\caminho\\omni-image-tools-mcp\\.venv\\Scripts\\python.exe", "-m", "src.server"],
      "cwd": "C:\\caminho\\omni-image-tools-mcp",
      "environment": {
        "OMNI_VISION_PROVIDER": "ollama",
        "OMNI_VISION_DEFAULT_MODEL": "qwen3-vl:2b"
      },
      "enabled": true
    }
  }
}

Ollama (local, gratuito)

"environment": {
  "OMNI_VISION_PROVIDER": "ollama",
  "OMNI_VISION_DEFAULT_MODEL": "qwen3-vl:2b"
}

OpenAI (nuvem, pago)

Requer API key.

"environment": {
  "OMNI_VISION_PROVIDER": "openai",
  "OMNI_VISION_API_KEY": "sk-proj-sua-chave-aqui",
  "OMNI_VISION_DEFAULT_MODEL": "gpt-5.4-mini"
}

OpenRouter (nuvem, barato)

Requer API key.

"environment": {
  "OMNI_VISION_PROVIDER": "openrouter",
  "OMNI_VISION_API_KEY": "sk-or-v1-sua-chave-aqui",
  "OMNI_VISION_DEFAULT_MODEL": "qwen/qwen3-vl-32b-instruct"
}

MiniMax (nuvem, MiniMax-M3)

Requer API key da MiniMax.

"environment": {
  "OMNI_VISION_PROVIDER": "minimax",
  "MINIMAX_API_KEY": "{env:MINIMAX_API_KEY}",
  "OMNI_VISION_DEFAULT_MODEL": "MiniMax-M3"
}

Para a plataforma China, adicione "MINIMAX_BASE_URL": "https://api.minimaxi.com/v1".

Lembrete: O command deve apontar para o python.exe da pasta .venv do projeto. Depois de alterar, reinicie o opencode.

Também funciona no Claude Desktop e Cursor IDE.

🖥️ Gerenciamento de Memória GPU

Só se aplica se você usa Ollama (local).

Quando você usa Ollama, o modelo fica carregado na memória da placa de vídeo. Se você pedir para carregar outro modelo, o sistema automaticamente descarrega o anterior antes de carregar o novo — evitando que a memória estoure.

uv run python scripts/cli.py gpu-status                    # Ver o que está carregado
uv run python scripts/cli.py gpu-status --unload-ollama modelo  # Forçar descarregar

Isso tudo acontece automagicamente — você não precisa se preocupar.

❓ Problemas Comuns

📁 Estrutura do Projeto

src/
├── server.py              # Servidor que se comunica com a IA
├── config.py              # Configurações
├── providers/
│   ├── ollama.py          # Conexão com Ollama (local)
│   ├── openrouter.py      # Conexão com OpenRouter (nuvem)
│   ├── openai.py          # Conexão com OpenAI (nuvem)
│   └── minimax.py         # Conexão com MiniMax (nuvem, M3)
├── tools/
│   ├── vision/            # Ferramentas de visão (IA)
│   └── processing/        # Ferramentas de processamento (PIL)
└── utils/
    └── gpu_memory.py      # Controle de memória da GPU

📄 Licença

MIT