mcp-recognize-image

An MCP (Model Context Protocol) server that gives text-only models the ability to "see" images. It routes image-recognition requests through configurable multimodal (vision) LLM providers, with priority-ordered automatic fallback: if the top provider fails (auth / rate-limit / error / timeout), the next is tried.

Install (end users)

uvx mcp-recognize-image

Install uv first if needed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or with pip:

pip install mcp-recognize-image

Configure

Works out of the box with the bundled default providers (free vision endpoints pre-filled). You only need to set API keys for the providers you have:

export GEMINI_API_KEY=...         # free tier: https://aistudio.google.com
export SILICONFLOW_API_KEY=...    # free tier: https://cloud.siliconflow.cn
export OPENROUTER_API_KEY=...     # free models: https://openrouter.ai

Custom endpoint (zero config file)

Point it at any OpenAI-compatible endpoint (OpenAI, Azure OpenAI, Ollama, LM Studio, DeepSeek, Moonshot, …) with three env vars — no config file needed. The API key lives in the env (never on disk):

export VISION_BASE_URL="https://api.openai.com/v1"
export VISION_API_KEY="sk-..."
export VISION_MODEL="gpt-4o"
# optional: VISION_ADAPTER (openai_compat|gemini|anthropic, default openai_compat)
# optional: VISION_PRIORITY (default 0 = tried first)

With these set and no config file, only this custom provider is used. In an MCP client config, put the same vars in the env block.

Config path resolution (only if you customize the provider list):

1. VISION_MCP_CONFIG env var (absolute path)
2. ~/.config/vision-mcp/config.toml
3. bundled config.example.toml (fallback — used by default)

To customize the provider list, copy the bundled example and edit (from a source checkout):

mkdir -p ~/.config/vision-mcp
cp src/vision_mcp/config.example.toml ~/.config/vision-mcp/config.toml

Free vision models rotate. Re-verify with (from a source checkout):

python scripts/verify_free_models.py              # OpenRouter list is public
SILICONFLOW_API_KEY=... python scripts/verify_free_models.py
GEMINI_API_KEY=... python scripts/verify_free_models.py

Use with Claude Desktop / Cursor / Cline

Add to your MCP client config (Claude Desktop: claude_desktop_config.json).

With uvx (recommended, zero install):

{
  "mcpServers": {
    "vision": {
      "command": "uvx",
      "args": ["mcp-recognize-image"],
      "env": { "GEMINI_API_KEY": "..." }
    }
  }
}

With a local install:

{
  "mcpServers": {
    "vision": {
      "command": "mcp-recognize-image",
      "env": { "GEMINI_API_KEY": "..." }
    }
  }
}

The tools

recognize_image(image, prompt="Describe this image in detail.") — image is a local file path, an http(s) URL, or a data: URI. Returns the model's text answer, or an Error: ... string if every provider failed.

recognize_images(images: list[str], prompt="Describe these images in order.") — recognize/compare multiple images in one call (parsed in list order). Each entry is a file path, URL, or data: URI. Good for "describe each in order" or "compare these".

recognize_clipboard_image(prompt="Describe this image in detail.") — reads the image currently on the system clipboard. Use this when the user pastes/copies an image into the chat and there is no file path. (macOS/Windows; on Linux it returns a "not supported" error.) Requires Pillow (included).

Adapters

Develop

git clone <repo>
cd mcp-recognize-image
uv venv --python 3.13 .venv
uv pip install -e ".[dev]"
pytest -q

Publish (maintainer)

uv build      # builds wheel + sdist into dist/
uv publish    # uploads to PyPI (set PYPI_TOKEN env or pass --token)