omni-image-tools-mcp

A Model Context Protocol (MCP) server that gives computer vision to AI models. It lets AI "see" images: describe, compare, extract text, crop objects, and more.

11 tools · 5 providers · Works with opencode, Claude, Cursor

Table of Contents

• Why this exists
• Which provider to use?
• Pick your model
• Quickstart
• Installation
• Tools
• Configuration
• Provider setup
• Security
• GPU memory management
• Troubleshooting
• Development
• License

Why this exists

If you use an MCP-aware LLM client and want your AI to see images, you need a local bridge between the client and a vision model. This server is that bridge:

• Speaks MCP over stdio (works with any compliant client)
• Supports local (Ollama, LM Studio) and cloud (OpenAI, OpenRouter, MiniMax) vision providers
• Preprocesses images automatically (resize, compress, cache) before sending them upstream
• Exposes both AI vision tools (describe, OCR, object detection, compare) and deterministic processing tools (crop, convert, resize, download)
• extract_object finds and crops any object described in text — automatically

Which provider to use?

If you have a GPU → Ollama

The model runs on your computer, using your graphics card. Free, private, no internet needed.

Limit: your GPU has finite memory — that's why it's 1 image at a time with smaller models.

If you have no GPU or want more quality → Cloud

The model runs in the cloud (OpenAI, OpenRouter, MiniMax). Pay-per-use, needs an API key, no image limits.

Pick your model

⚠️ Memory matters: with 4GB of VRAM use qwen3-vl:2b; with 6GB+ you can use qwen3-vl:4b. Cloud models don't touch your GPU.

Quickstart

# 1. Install via pip (requires uv: https://docs.astral.sh/uv/)
pip install omni-image-tools-mcp

# 2. If using Ollama (free, local):
export OMNI_VISION_PROVIDER=ollama
export OMNI_VISION_DEFAULT_MODEL=qwen3-vl:2b

# 3. Configure your MCP client (see below) and restart it

💡 Tip: want to use the cloud? See Provider setup below. The omni-image-tools console script starts the MCP server over stdio and waits for the client to connect.

Installation

Prerequisites

• Python 3.10+
• A vision provider: Ollama installed locally, or an API key for one of the cloud providers

Option A — From PyPI (recommended for end users)

pip install omni-image-tools-mcp

The omni-image-tools console script is installed automatically. Configure your MCP client (examples below), then restart it.

Option B — From source (for contributors)

git clone https://github.com/alexlivre/omni-image-tools-mcp.git
cd omni-image-tools-mcp
uv sync
uv sync --extra dev

Tools

👁️ Vision (use AI)

Why does Ollama have a 1-image limit? Because GPU memory is limited. Sending several images at once can blow the memory and freeze everything. The system automatically manages this — no such problem in the cloud.

🛠️ Processing (no AI, fast)

⚙️ System

Configuration

Environment variables

Provider setup

Option A: Ollama (free, local)

Requires Ollama installed and the model pulled (ollama pull qwen3-vl:2b)

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

Option B: OpenAI (cloud, paid)

Requires an OpenAI API key

export OMNI_VISION_PROVIDER=openai
export OMNI_VISION_API_KEY=sk-proj-your-key-here
export OMNI_VISION_DEFAULT_MODEL=gpt-5.4-mini

Option C: OpenRouter (cloud, cheap)

Requires an OpenRouter API key

export OMNI_VISION_PROVIDER=openrouter
export OMNI_VISION_API_KEY=sk-or-v1-your-key-here
export OMNI_VISION_DEFAULT_MODEL=qwen/qwen3-vl-32b-instruct

Option D: MiniMax (cloud, MiniMax-M3 multimodal)

Requires a MiniMax API key. Supports both platforms:

• International (minimax.io) — default, no extra config
• China (minimaxi.com) — set MINIMAX_BASE_URL=https://api.minimaxi.com/v1

# International (default)
export OMNI_VISION_PROVIDER=minimax
export MINIMAX_API_KEY=your-key-here

# China (optional)
export MINIMAX_BASE_URL=https://api.minimaxi.com/v1

💡 The key can come from OMNI_VISION_API_KEY or MINIMAX_API_KEY (the latter is used as a fallback — handy if it's already in your system environment variables).

LM Studio (local)

Requires LM Studio running with the server enabled on port 1234.

export OMNI_VISION_PROVIDER=lmstudio
export LMSTUDIO_BASE_URL=http://localhost:1234
export OMNI_VISION_DEFAULT_MODEL=qwen2.5-vl-7b-instruct

Configuring MCP clients

opencode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "omni-image-tools": {
      "type": "local",
      "command": ["omni-image-tools"],
      "environment": {
        "OMNI_VISION_PROVIDER": "ollama",
        "OMNI_VISION_DEFAULT_MODEL": "qwen3-vl:2b"
      },
      "enabled": true
    }
  }
}

MiniMax example

{
  "mcp": {
    "omni-image-tools": {
      "type": "local",
      "command": ["omni-image-tools"],
      "environment": {
        "OMNI_VISION_PROVIDER": "minimax",
        "MINIMAX_API_KEY": "{env:MINIMAX_API_KEY}",
        "OMNI_VISION_DEFAULT_MODEL": "MiniMax-M3"
      },
      "enabled": true
    }
  }
}

Note: if the server is installed in a virtualenv, point command at the omni-image-tools executable inside that venv. After changing config, restart opencode.

Also works with Claude Desktop and Cursor.

Security

• SSRF: download_image blocks private/loopback/link-local IPs (e.g. 169.254.169.254), hosts that resolve to them, and revalidates every redirect.
• Path traversal: all image_path values are resolved (resolve() follows symlinks); with OMNI_ALLOWED_DIRS configured, paths outside the sandbox are rejected.
• Limited downloads: download is streamed with a 20 MB cap (Content-Length + byte counter).
• Privacy: get_image_info returns EXIF off by default (include_exif); if enabled and GPS is present, a warning is added.

GPU memory management

Only applies if you use Ollama (local).

When you use Ollama, the model stays loaded in your GPU memory. If you ask to load another model, the system automatically unloads the previous one first — preventing memory overflow.

omni-image-tools gpu-status                    # See what's loaded
omni-image-tools gpu-status --unload-ollama model  # Force unload

This all happens automagically — you don't need to worry about it.

Troubleshooting

Development

uv sync
uv sync --extra dev

# Test (pytest)
uv run pytest tests/ -v

# Lint / format / type
uv run ruff check src/ tests/
uv run black src/ tests/ --line-length 100
uv run mypy src/ --python-version 3.10

# CLI for manual testing
uv run python scripts/cli.py analyze --image test.jpg --prompt "Describe this"

License

MIT © 2026 Alex Santos (@alexlivre)