Content
# Vision MCP Server
Provide image understanding capabilities for MCP clients (such as Claude Code) by analyzing image content through visual models from Aliyun Baizhan, OpenAI, OpenRouter, etc., and returning descriptions tailored for software development.
## Quick Start
```bash
pip install -e .
python -m vision_mcp_server
```
## Environment Variables
### Required
| Variable | Description |
|------|------|
| `DASHSCOPE_API_KEY` | Baizhan API Key (default Provider) |
### Provider Switching
| Variable | Default Value | Description |
|------|--------|------|
| `VISION_PROVIDER` | `bailian` | Provider name: `bailian` / `openai` / `openrouter` |
| `VISION_BASE_URL` | By Provider | Override API endpoint address |
| `VISION_MODEL` | By Provider | Override model name |
| `VISION_API_KEY` | By Provider | Override API Key |
| `VISION_MAX_TOKENS` | `600` (quick) / `1500` (detailed) | Maximum output token count |
| `VISION_MODELS` | — | Model fallback list, comma-separated (see below) |
### Model Fallback Router
Set `VISION_MODELS` environment variable to specify a list of models to try in order:
```bash
VISION_MODELS=qwen-vl-max,qwen-vl-plus,qwen-3.7 python -m vision_mcp_server
```
When the current model returns **HTTP 429** (rate limiting), **quota exceeded**, or **insufficient balance**, automatically switch to the next model. If all models fail, return an error.
Behavior unchanged if `VISION_MODELS` is not set (determined by `VISION_MODEL` or Provider default).
### Caching
Supports disk caching with a default 7-day TTL. Environment variables control:
| Variable | Default Value | Description |
|------|--------|------|
| `VISION_CACHE_ENABLED` | `true` | Set to `false` to disable caching |
| `VISION_CACHE_TTL` | `604800` | Cache expiration time (seconds) |
| `VISION_CACHE_DIR` | By platform | Cache storage directory, Windows: `%LOCALAPPDATA%/vision-mcp-server/cache` |
### Provider Defaults
| Provider | Model | Endpoint |
|----------|------|------|
| `bailian` | `qwen-vl-max` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| `openai` | `gpt-4o-mini` | `https://api.openai.com/v1` |
| `openrouter` | `openai/gpt-4o` | `https://openrouter.ai/api/v1` |
## Tool: `image_understand`
```python
image_understand(image_path: str, prompt: str | None = None, mode: str = "quick", force_refresh: bool = False) -> dict
```
### Parameters
| Parameter | Type | Default | Description |
|------|------|------|------|
| `image_path` | string | Required | Local image path (PNG/JPG/GIF/WebP) or HTTP URL |
| `prompt` | string | `None` | Custom prompt, if not provided, an automatic prompt will be chosen |
| `mode` | string | `"quick"` | `"quick"` for brief and fast analysis (5-10s) / `"detailed"` for seven-dimension detailed analysis |
| `force_refresh` | bool | `false` | Skip cache and re-analyze the image |
### Return
```json
{
"description": "Image content description (Markdown format)",
"model": "qwen-vl-max",
"status": "success"
}
```
### Two Modes
| Mode | Time | Output | Applicable Scenarios |
|------|------|------|----------|
| `quick` | 5-10s | 3-4 key points | Daily image understanding, quick comprehension |
| `detailed` | 15-30s | Seven-dimension analysis | UI restoration, design review, chart extraction |
### Seven Dimensions of Detailed Mode
1. UI Layout — Overall structure, block position, and proportion
2. Component Structure — Button/form/table hierarchy and nesting
3. Page Hierarchy — Information level relationship
4. Color Scheme — Main color tone, design style, and light/dark mode
5. OCR Text — All visible text and positions
6. Chart Information — Chart type, data dimensions, and key values
7. Front-end Implementation Features — CSS framework, responsiveness, animation, and icon library
## Claude Code Configuration
Create `.mcp.json` in the project root directory:
```json
{
"mcpServers": {
"vision": {
"command": "python",
"args": ["-m", "vision_mcp_server"],
"cwd": "E:/MCP",
"env": {
"DASHSCOPE_API_KEY": "sk-xxx"
}
}
}
}
```
Reconnect after installation.
## Project Structure
```
src/vision_mcp_server/
├── __init__.py
├── __main__.py # Entry point
├── server.py # FastMCP + image_understand tool
├── vision.py # Multi-provider visual client
└── image_utils.py # Image path detection + Base64 encoding
```
