Content
# Visual Understanding MCP Server
Provide image understanding capabilities for coding models that do not support visual perception.
## Principle
When a coding model (e.g., GLM-5.1) encounters an image, it automatically calls the MCP tool `understand_image`, which uses a visual model to recognize the image and returns the result as text to the coding model for continued inference. No model switching is required, and the context remains uninterrupted.
```
User pastes screenshot → Coding model calls understand_image → Visual model recognizes → Text description returns → Continues coding
```
## Installation Method 1: Using PyPI / uvx (Recommended)
MCP configuration example:
```json
{
"mcpServers": {
"visual-understand": {
"command": "uvx",
"args": ["visual-understand-mcp"],
"env": {
"VISION_API_BASE": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"VISION_MODEL": "qwen-vl-max",
"VISION_API_KEY": "sk-xxx"
}
}
}
}
```
## Installation Method 2: Running from Local Source Code
```json
{
"mcpServers": {
"visual-understand": {
"command": "uv",
"args": [
"--directory", "/path/to/visual-understand-mcp",
"run", "visual-understand-mcp"
],
"env": {
"VISION_API_BASE": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"VISION_MODEL": "qwen-vl-max",
"VISION_API_KEY": "sk-xxx"
}
}
}
}
```
## Configuration Items
| Variable | Description | Default Value |
| --- | --- | --- |
| `VISION_API_BASE` | Visual model API address | None (required) |
| `VISION_MODEL` | Visual model name | None (required) |
| `VISION_API_KEY` | Visual model key | None (required) |
| `VISION_TEMPERATURE` | Output randomness | `0.1` |
| `VISION_MAX_TOKENS` | Maximum output length | `12000` |
| `VISION_TIMEOUT` | Request timeout (seconds) | `120` |
| `VISION_SYSTEM_PROMPT` | Visual model system prompt | See below |
The first three are required, and the rest are optional. Configuration can also be written to `~/.visual-understand-mcp/config.json`, with env having higher priority.
Default system prompt:
> You are an image analysis assistant, used only to understand image content. Please analyze the image according to the following structure, adjusting the level of detail based on the actual content: 1. **Text Content** — Extract all visible text from the image, preserving the original format and hierarchical relationship. 2. **Error Messages and Code** — If the image contains error messages or code snippets, output them exactly as they appear, without any rewriting or summarization; if not, skip this item. 3. **Visual Layout and Elements** — Describe the spatial arrangement, size, color, and relationships between key elements. For UI screenshots, identify component types and their states. 4. **Data and Metrics** — For charts and tables, extract numerical values, axis labels, tags, trends, and anomalous data points. 5. **Overall Overview** — Summarize the image's theme, scene, and key information, providing a complete contextual understanding. Skip inapplicable parts. Only describe visible content in the image, without making inferences, guesses, or extended interpretations. Maintain precision and objectivity, without speculating about invisible content.
## Recommended to Write in CLAUDE.md
```markdown
When performing image recognition tasks, use the visual-understand MCP's understand_image tool.
```
## Local Debugging
```bash
uv run mcp dev src/visual_understand_mcp/server.py
```
## License
MIT
