Content
# Vision MCP Server
Provide image understanding capabilities for LLMs lacking multimodal abilities (e.g., DeepSeek). Forwards images to visual models via OpenAI-compatible API, exposing `describe_image` as an MCP tool, accessible to any AI Agent supporting the MCP protocol (Claude Code, Cline, Continue.dev, etc.).
## Tool List
## I. Configuration
All backend configurations (API address, key, model name) are managed through the `.env` file in the project root directory, **eliminating the need to repeatedly pass environment variables when registering MCP**. Modifying the configuration and restarting the Agent will take effect.
### 1. Installation
```bash
uv venv && uv pip install -e .
```
### 2. Configure Backend
Copy the configuration template and fill in the actual values:
```bash
cp .env.example .env
```
`.env` file content:
```
VISION_API_BASE=https://api.siliconflow.cn/v1 # Visual model API address
VISION_API_KEY=sk-your-key-here # API key
VISION_MODEL=Qwen/Qwen3.6-35B-A3B # Model name
VISION_MAX_TOKENS=2000 # Maximum output tokens (optional)
```
> `.env` is automatically loaded when the Server starts. Modifying it and restarting the Agent will take effect, **no need to re-register MCP**.
| Variable | Required | Default Value | Description |
|----------|----------|---------------|-------------|
| `VISION_API_BASE` | Yes | `http://localhost:8000/v1` | API address, without `/chat/completions` suffix |
| `VISION_API_KEY` | As needed | `not-needed` | API key (leave blank for local deployment) |
| `VISION_MODEL` | Yes | `qwen-vl-plus` | Visual model name |
| `VISION_MAX_TOKENS` | No | `2000` | Maximum tokens per response |
### 3. Register with AI Agent
**Method A (Recommended) — Using `.mcp.json`**
The project includes a `.mcp.json` file. Agents supporting this format (Cline, Continue.dev, etc.) will automatically recognize it:
```json
{
"mcpServers": {
"vision": {
"command": "uv",
"args": ["run", "vision-mcp"]
}
}
}
```
**Method B — Claude Code Manual Registration**
```bash
claude mcp add-json -s user vision '{
"command": "uv",
"args": ["run", "vision-mcp"]
}'
```
> All methods **do not require carrying the `env` field**, as configuration is managed by the `.env` file.
### 4. Verification
```bash
vision-mcp --help
```
Confirm the MCP Server status in the Agent is connected (Claude Code: `claude mcp list` → `vision: vision-mcp - ✓ Connected`).
## II. Working Principle
```
User: "Look at this screenshot"
→ AI Agent (DeepSeek, no visual capabilities)
→ Calls describe_image tool
→ Vision MCP Server: Reads local image → Base64 → POST visual model API
← Returns text description
→ AI Agent answers user based on description
```
## III. Tool Description
### describe_image — Understand Image Content
| Parameter | Required | Type | Description |
|----------|----------|------|-------------|
| `image_path` | Yes | `string` | Local **absolute path** of the image |
| `prompt` | No | `string` | Description focus, e.g., "extract all text", "describe chart trends" |
| `max_tokens` | No | `int` | Overrides environment variable `VISION_MAX_TOKENS`, controls output length as needed |
- **Supported formats**: PNG / JPG / JPEG / GIF / WebP / BMP
- **Single file limit**: ≤ 20 MB
### vision_ping — Diagnose Connectivity
Returns server status information for troubleshooting MCP communication.
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call",\
"params":{"name":"vision_ping","arguments":{"msg":"hello"}}}' | vision-mcp
```
## IV. Usage Examples
```
User: Look at @error_screenshot.png for error information
User: Analyze @architecture.png for system design issues
User: Convert @data_table.png to markdown table
User: @chart.png describe data trends, within 200 characters
```
## V. Update Configuration
Modifying the `.env` file and **restarting the AI Agent** will take effect, no need to re-register MCP.
To change the Provider's API address, refer to the following configuration:
| Provider | `VISION_API_BASE` | Recommended `VISION_MODEL` |
|----------|-------------------|----------------------------|
| SiliconFlow | `https://api.siliconflow.cn/v1` | `Qwen/Qwen3.6-35B-A3B` |
| Local vLLM | `http://10.0.0.5:8000/v1` | `Qwen3-VL-32B-Instruct` |
| Local Ollama | `http://localhost:11434/v1` | `llava:13b` |
| One-API Gateway | `https://your-gateway.com/v1` | `gpt-4o` |
## Frequently Asked Questions
### Failed to connect?
1. Confirm `vision-mcp --help` is executable
2. Check API connectivity: `curl $VISION_API_BASE/models`
3. Run `vision-mcp` to view stderr logs
### Returns garbled or empty content?
- Try converting the image to PNG format
- Reduce image size (Base64 increases volume by approximately 33%)
- Switch to a more powerful visual model
### Will image data be stored?
No. Images are sent to the visual API via Base64 encoding and HTTPS, and the Server does not store or cache locally. Be cautious not to transmit sensitive images when using public APIs.
