readpic MCP Server

通过 MCP 协议暴露 VL(Vision-Language)模型,让 AI 客户端(Claude Code / Claude 桌面版 / WorkBuddy)能直接理解、分析、描述本地图片。 图片识别模型所需连接信息可以从 onerouter dev 租户下的 vl 模型获取。

快速开始

readpic-mcp 通过 npx 分发,无需手动装 Python 依赖。首次启动时 shim 自动用 uv(或回退 venv)装 fastmcp/httpx,耗时数秒;之后走缓存秒启。

在 MCP 客户端配置

Claude Code(CLI):

claude mcp add readpic -s user \
  -e READPIC_API_URL=https://openapi-ai.cmaiot.cn/v1 \
  -e READPIC_API_KEY=sk-... \
  -e READPIC_MODEL=Qwen3-VL-8B-Instruct \
  -- npx -y github:tain-alphanume/readpic-mcp

Claude 桌面版 / WorkBuddy(claude_desktop_config.json 或 mcp.json):

{
  "mcpServers": {
    "readpic": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:tain-alphanume/readpic-mcp"],
      "env": {
        "READPIC_API_URL": "https://openapi-ai.cmaiot.cn/v1",
        "READPIC_API_KEY": "sk-...",
        "READPIC_MODEL": "Qwen3-VL-8B-Instruct"
      }
    }
  }
}

固定版本:args 改为 ["-y", "github:tain-alphanume/readpic-mcp#v0.1.0"](用 git tag)。 前置要求:Node 18+(npx 自带);Python 3.10+ 或 uv(shim 自动探测)。

功能

• 将 PNG / JPG / JPEG / WEBP / GIF / BMP 图片发送给 VL 模型,返回文本描述
• 单模型调用,同步返回结果
• 支持自定义 prompt、system prompt、temperature、seed
• 支持 response_format(json_object / json_schema)做结构化输出
• API 地址、密钥、模型名均从环境变量读取,不内嵌凭据

环境变量

变量	必填	说明
READPIC_API_URL	是	VL 模型 OpenAI 兼容 API 基址(如 https://openapi-ai.cmaiot.cn/v1)
READPIC_API_KEY	是	API 密钥(纯 sk-...,server 自动补 Bearer 前缀;请勿自带前缀)
READPIC_MODEL	是	模型名(如 Qwen3-VL-8B-Instruct)

三项缺失任一,server 启动即报 EnvironmentError。

MCP Tools

read_pic

读取/理解一张或多张图片,返回 JSON 字符串。

参数	类型	默认值	说明
image_paths	list[str]	必填	本地图片路径(支持 PNG/JPG/JPEG/WEBP/GIF/BMP)
prompt	str	请详细描述这张图片中的内容	给模型的文本指令
system_prompt	str	None	可选 system prompt
temperature	float	None	采样温度 0.0-1.0(vLLM 默认 ~0.7)
seed	int	None	随机种子(可复现)
response_format	dict	None	透传 vLLM response_format,如 {"type":"json_object"} 或 {"type":"json_schema","json_schema":{"name":"foo","schema":{...}}}

返回 JSON 结构:

{
  "images": [
    {"path": "E:/tmp/demo.png", "size_kb": 12.3}
  ],
  "prompt": "请详细描述这张图片中的内容",
  "response_format": null,
  "mode": "single",
  "results": [
    {
      "image": "demo.png",
      "model": "Qwen3-VL-8B-Instruct",
      "success": true,
      "result": "图中为一只橘色猫咪,趴在木质桌面上...",
      "error": null
    }
  ]
}

多图时 mode 为 "multi",image 为 "all"(所有图片一次性发给同一模型)。失败时 success 为 false、result 为 null、error 填错误信息。

results[].model 取响应中的 model 字段(后端实际处理请求的模型名),响应缺该字段时回退到请求的 READPIC_MODEL。

运行时

• uv 优先:shim 自动 uv run --with-requirements,uv 管理 ephemeral venv + 缓存,二次启动快。
• 无 uv 回退 venv:在 ~/.readpic-mcp/venv 建独立 venv 并 pip install -r requirements.txt;依赖就绪后跳过安装(哨兵文件 .installed 标记)。
• Python 3.10+,Node 18+。

注册辅助脚本(install.py)

若不想手写 MCP 配置,可用 install.py 交互式收集 url/key/model 并自动注册到各宿主。 install.py 不再安装依赖、不再拷贝 server.py,仅做注册(command 已配置为 npx -y github:tain-alphanume/readpic-mcp)。

# clone 仓库后本地运行
git clone https://github.com/tain-alphanume/readpic-mcp.git
cd readpic-mcp/python
python install.py                 # 自动检测宿主
python install.py --host claude   # 指定 Claude Code
python install.py --host claude-desktop  # 指定 Claude 桌面版
python install.py --host workbuddy       # 指定 WorkBuddy

安装流程(两步):

1. 交互式输入 READPIC_API_URL / READPIC_API_KEY / READPIC_MODEL(回车采用默认值)
2. 按宿主类型注册 MCP 服务器,把三个变量写入 env

install 脚本不内嵌凭据,每次安装时交互收集,避免源码泄露密钥。

支持平台

宿主	--host	注册方式
Claude Code (CLI)	claude	claude mcp add -s user 自动注册
Claude 桌面版	claude-desktop	自动写入 claude_desktop_config.json(深度合并)
WorkBuddy (腾讯)	workbuddy	打印 JSON 配置 + GUI 操作指引
自动检测	auto	按优先级自动选择

操作系统: Windows、macOS、Linux

注意事项

• 单张图片上限 20 MB
• 模型调用为同步阻塞,超时 300s
• 多图调用时,所有图片一次性发给同一模型(不再做分布/对比分发)

许可

内部使用。