<div align="center">

llm-vision

Give vision to vision-less LLMs — a local MCP server powered by Alibaba DashScope.

English | 简体中文

</div>

Vision-less models (e.g. DeepSeek) can't see images — but they don't have to. llm-vision is a local MCP server that acts as their eyes: hand it a local image path, and it returns a text description generated by Alibaba Cloud's vision models (qwen3-vl-plus / qwen3.5-ocr).

---

✨ Features

• Two tools, one pipeline — describe_image for general image understanding, extract_text for OCR & document parsing (ID cards, invoices, receipts)
• Bring your own model — model IDs configurable via environment variables, no code changes
• Zero-cost test suite — 22 tests, most run offline against mocked HTTP
• Portable setup — ship .mcp.json with your repo; works anywhere after uv sync
• Model-consumable errors — every tool returns a readable error string, never an exception

🚀 Quick Start

Prerequisites

• Python 3.12+ and uv
• A DashScope API key

1. Install

git clone https://github.com/1710782766/llm_vision.git && cd llm-vision
uv sync
export DASHSCOPE_API_KEY=sk-xxx   # or add to your shell profile

2. Register with Claude Code

The repo ships with a portable .mcp.json — just open Claude Code in the project directory and ask:

"Use describe_image to look at path/to/your/image.jpg and tell me what's in it."

Approve the server connection once, and every future session has vision.

Prefer the CLI? Register manually:

claude mcp add llm-vision --env DASHSCOPE_API_KEY=sk-xxx -- uv run python main.py

🛠 Tools

Tool	Arguments	Description
describe_image	image_path (required) · prompt (optional)	Describe an image, or answer questions about it
extract_text	image_path (required) · prompt (optional)	OCR & text localization — documents, ID cards, invoices; ask for structured output (e.g. "extract the name and ID number as JSON")

Supported formats: jpg · jpeg · png · webp · gif · bmp — single file < 10 MB.

⚙️ Configuration

Variable	Required	Default	Description
DASHSCOPE_API_KEY	✅	—	DashScope API key (sk- prefix)
LLM_VISION_MODEL	—	qwen3-vl-plus	Vision model used by describe_image
LLM_VISION_OCR_MODEL	—	qwen3.5-ocr	OCR model used by extract_text
LLM_VISION_TIMEOUT	—	60	Request timeout (seconds)

🧠 Model Selection

• qwen3-vl-plus (default vision) — benchmarked as the only hallucination-free option in our model evaluation; qwen3.7-plus is a promising upgrade candidate
• qwen3.5-ocr (default OCR) — cheap, and notably strong at document & card-key-value extraction
• ⚠️ The qwen3-vl-plus-latest alias has been retired (returns 404) — use stable model IDs

🏗 Architecture

main.py (MCP server)
  ├── describe_image(path, prompt?)   → LLM_VISION_MODEL
  ├── extract_text(path, prompt?)     → LLM_VISION_OCR_MODEL
  └── _analyze_image pipeline
        → image_loader      path/extension/10MB validation, base64 + MIME
        → dashscope_client  httpx → DashScope OpenAI-compatible endpoint

Tools always return a string: the model's answer on success, a readable Chinese error message on failure — never an exception to the client.

🔒 Security & Privacy

• DASHSCOPE_API_KEY lives only in your environment — never in .mcp.json or in git
• When a tool is invoked, the image is sent as base64 to Alibaba DashScope — only hand the model images you're comfortable leaving your machine

🧪 Development

uv run pytest tests/ -q                                   # full suite (22 tests, mostly offline)
uv run python scripts/smoke_test.py [image_path ...]      # real-API smoke test (billed, ~¥0.01/call); pass paths or provide your own under images/
uv run python scripts/compare_models.py qwen3-vl-plus qwen3.7-plus   # model bake-off (billed)

Developer notes for Claude Code: see CLAUDE.md.