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 自动探测)。

Related MCP server: Photo AI Studio MCP Server

功能

• 将 PNG / JPG / JPEG / WEBP / GIF / BMP 图片发送给 VL 模型,返回文本描述

• 单模型调用,同步返回结果

• 支持自定义 prompt、system prompt、temperature、seed

• 支持 response_format(json_object / json_schema)做结构化输出

• API 地址、密钥、模型名均从环境变量读取,不内嵌凭据

环境变量

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

MCP Tools

read_pic

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

返回 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 脚本不内嵌凭据,每次安装时交互收集,避免源码泄露密钥。

支持平台

操作系统: Windows、macOS、Linux

注意事项

• 单张图片上限 20 MB

• 模型调用为同步阻塞,超时 300s

• 多图调用时,所有图片一次性发给同一模型(不再做分布/对比分发)

许可

内部使用。