# Vision MCP Server

Python 实现的 MCP (Model Context Protocol) 图片分析服务器 —— 为纯文本大模型提供视觉能力。

> 参考自 [Markusbetter/vision-mcp-server](https://github.com/Markusbetter/vision-mcp-server)（Node.js / TypeScript），在其基础上增加了大图自动缩放、多 API 提供商支持等功能。

### 功能特点

- 单一工具：`analyze_image` — 分析图片内容并提供详细描述
- 支持**本地图片文件**和**远程 HTTP(S) URL**
- **自动缩放**：超过 2048×2048 像素的图片会自动等比缩放到长边 2047px 再发送，避免超大图直接报错
- **多提供商支持**：兼容任意 OpenAI 兼容 API，通过环境变量切换——OpenAI、Azure、vLLM、Ollama、ModelScope 等均可
- 全部通过环境变量配置，无需配置文件

### 安装

#### uv（推荐）

```bash
# 克隆仓库
git clone https://github.com/Jian-1197/vision-mcp.git
cd vision-mcp

# 安装（editable 模式，修改源码即时生效）
uv tool install -e .
```

安装完成后 `vision-mcp` 命令即全局可用。

> 需要 Python ≥ 3.10。

#### Conda

```bash
conda create -n mcp python=3.10 -y
conda activate mcp
pip install -e /path/to/vision-mcp
```

#### venv / pip

```bash
python -m venv .venv
source .venv/bin/activate       # Linux/macOS
.venv\Scripts\activate          # Windows
pip install -e /path/to/vision-mcp
```

### 环境变量配置

| 变量 | 必填 | 说明 |
|------|------|------|
| `VISION_BASE_URL` | ✅ | API 基础地址 |
| `VISION_API_KEY` | ✅ | API 密钥 |
| `VISION_MODEL` | ✅ | 模型名 |

### MCP 客户端配置

本服务通过 **stdio** 传输，运行命令为 `vision-mcp`。

以 Claude Desktop 为例：

```json
{
  "mcpServers": {
    "vision": {
      "command": "vision-mcp",
      "env": {
        "VISION_BASE_URL": "https://api.openai.com/v1",
        "VISION_API_KEY": "sk-your-key-here",
        "VISION_MODEL": "gpt-4o"
      }
    }
  }
}
```

若使用 Reasonix（1.x 配置文件路径为 `~\AppData\Roaming\reasonix\config.toml`，可在软件中查看，或直接在 MCP 界面添加运行命令及环境变量）：

```toml
[[plugins]]
name    = "vision"
type    = "stdio"
command = "vision-mcp"
env     = { VISION_BASE_URL = "https://api.openai.com/v1", VISION_API_KEY = "sk-your-key-here", VISION_MODEL = "gpt-4o" }
```

### 免费服务示例

#### 智谱 GLM-4.6V-Flash

智谱提供的免费视觉模型，128K 上下文，支持图片、视频、文件理解。[文档](https://docs.bigmodel.cn/cn/guide/models/free/glm-4.6v-flash)

API Key 获取：访问 [智谱开放平台](https://open.bigmodel.cn/) → 注册 → API Keys

```json
{
  "mcpServers": {
    "vision": {
      "command": "vision-mcp",
      "env": {
        "VISION_BASE_URL": "https://open.bigmodel.cn/api/paas/v4",
        "VISION_API_KEY": "你的智谱APIKey",
        "VISION_MODEL": "glm-4.6v-flash"
      }
    }
  }
}
```

#### 魔搭社区 ModelScope

ModelScope 提供免费视觉模型调用额度，每日 2k 次。[文档](https://modelscope.cn)

API Token 获取：访问 [ModelScope](https://modelscope.cn) → 个人中心 → API 令牌

```json
{
  "mcpServers": {
    "vision": {
      "command": "vision-mcp",
      "env": {
        "VISION_BASE_URL": "https://api-inference.modelscope.cn/v1",
        "VISION_API_KEY": "你的ModelScopeToken",
        "VISION_MODEL": "Qwen/Qwen3-VL-30B-A3B-Instruct"
      }
    }
  }
}
```

### 工作原理

1. 接收图片（本地路径 → 读取文件；URL → HTTP 下载）
2. 若图片超过 2048px，用 Pillow 等比缩放
3. 编码为 base64 data URI
4. 发送到 `{VISION_BASE_URL}/chat/completions`（OpenAI 兼容格式）
5. 返回模型的文字描述

### 许可证

MIT