Content
# mcp_images
**MCP Image Analysis Server** — Analyze local images, clipboard screenshots, or Base64 image data directly in AI tools.
Send images to OpenAI-compatible VLM APIs (Ollama / vLLM / DashScope / OpenAI, etc.) and return structured analysis results.
## Quick Start
### Method 1: Download Precompiled Binary (Recommended)
Download the binary file for your platform from [Releases](https://github.com/LiveBigOrange/mcp_images/releases/latest).
### Method 2: Build from Source
```bash
# Linux / macOS
make build # Build for current platform
make build-all # Cross-platform build (Windows/Linux/macOS)
# Windows
./build.ps1 # Build for current platform
./build.ps1 -Action build-all # Cross-platform build
```
Build output will be in the `bin/` directory.
### Configuration
Add the following to `mcp.json` in your AI tool (using Ollama as an example):
```json
{
"mcpServers": {
"mcp_images": {
"command": "/path/to/mcp_images",
"env": {
"VLM_API_BASE": "http://localhost:11434/v1/chat/completions",
"VLM_MODEL": "qwen2.5vl:7b"
}
}
}
}
```
See [full documentation](https://livebigorange.github.io/mcp_images/) for more configuration examples (vLLM / DashScope / OpenAI / opencode).
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `VLM_API_BASE` | VLM API address (required) | — |
| `VLM_MODEL` | Model name (required) | — |
| `VLM_API_KEY` | API Key (optional for local models) | — |
| `VLM_TIMEOUT` | HTTP timeout in seconds | `60` |
| `VLM_LOG_LEVEL` | Log level | `warn` |
## Tools
- `describe_image_file` — Analyze local image files
- `describe_clipboard_image` — Read clipboard screenshots and analyze
- `describe_base64_image` — Analyze Base64-encoded images
## Documentation
Full documentation (including multi-scenario configuration examples and use cases): [livebigorange.github.io/mcp_images](https://livebigorange.github.io/mcp_images/)
## Build
```bash
# Linux / macOS
make build # Build for current platform
make build-all # Cross-platform build
make test # Run tests
make lint # Code linting
# Windows
./build.ps1 # Build for current platform
./build.ps1 -Action test # Run tests
./build.ps1 -Action lint # Code linting
```
## Architecture
```
AI Tool → stdio JSON-RPC → Image Processing → VLM API → Structured Results
```
Single Go binary + stdio JSON-RPC, zero-dependency runtime.
## Contact
For questions or suggestions, contact [yzn5555@163.com](mailto:yzn5555@163.com)
## License
[MIT](./LICENSE)
