mcp-recognize-image 0.1.0

MCP server that lets text-only models 'see' images via configurable vision LLM providers with priority fallback

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

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 tool

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.

Adapters

adapter	providers
openai_compat	OpenAI, SiliconFlow, OpenRouter, any OpenAI-compatible endpoint
gemini	Google Gemini (native API)
anthropic	Anthropic Claude (native API)

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)