ImageMCP — 给文本模型配一双"眼睛"

部分大模型（如 DeepSeek）不具备图片识别能力。ImageMCP 是一个常驻系统托盘的桌面应用，内置标准 MCP 服务，把图片交给具备多模态能力的模型（默认小米 MiMo mimo-v2.5）识别后，把答案返回给文本模型。任何支持 MCP 的 Code Agent（Claude Code、opencode、Cline、Cursor、Windsurf 等）都能接入。

文件说明

Related MCP server: mcp-six-eyes

快速开始（接收方，无需安装 Python）

第 1 步：放置并启动

把 imagemcp.exe 和 config.json 放到同一目录（如 D:\ImageMCP\），双击 imagemcp.exe：

• 桌面右下角出现托盘图标；

• 自动弹出设置窗口，顶部横幅显示服务状态；

• 后台自动启动 MCP 服务：http://127.0.0.1:9847/mcp。

第 2 步：填写 API 配置

在设置窗口填入：

点「保存并检测」→ 顶部横幅变绿色「✓ 服务正常：图片识别可用」即配置成功。

第 3 步：让 AI 自助安装到全局（推荐）

点设置窗口的「复制安装提示词」按钮（或直接打开 ai_rules/IMAGE_RULES.md）， 把内容粘贴给你的 AI agent（Claude Code、opencode、Cursor、Codex、Windsurf、Cline…都行）。

AI 收到后按提示词执行：

1. 自查身份——判断自己是什么 agent（查看运行环境 / 检测自己的全局配置目录）；

2. 只安装到当前 agent——把「图片识别规则」写入它自己的全局规则文件 （如 Claude Code → ~/.claude/CLAUDE.md，opencode → ~/.config/opencode/AGENTS.md）； ⚠️ 不会安装到其他 agent，不会枚举安装所有；

3. 幂等（重复安装不会产生重复内容）；可选顺手注册 MCP（claude mcp add --scope user 等）。

规则核心一句话：

图片必须调用 analyze_image 工具；禁止用 Read 工具或模型自身视觉读图。 你是一个纯文本模型，不具备直接查看或理解图片的能力。当用户上传图片或提及图片时，严禁尝试直接分析图片内容或使用内置的 Read/View 功能，必须且只能调用 MCP 工具 [imagemcp] 来处理图片。图片必须调用 analyze_image 工具；禁止用 Read 工具或模型自身视觉读图。

之后所有项目、所有会话都会自动生效，AI 收到图片会直接走 MCP 识别，不再用自己的视觉硬试。

卸载：让 AI 删除规则文件中 <!-- ImageMCP-rules-start --> 与 <!-- ImageMCP-rules-end --> 之间的内容。

第 4 步：开始使用

在对话中让助手"看这张图"，它会按全局规则调用 analyze_image 识别图片并回答。

各 MCP 客户端手动接入方式

所有客户端都连同一个地址：

地址：http://127.0.0.1:9847/mcp
类型：Streamable HTTP（部分客户端写作 HTTP / SSE）

opencode 全局配置示例（~/.config/opencode/opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "imagemcp": {
      "type": "remote",
      "url": "http://127.0.0.1:9847/mcp",
      "enabled": true
    }
  }
}

代理提示：若连接失败且本机开了系统代理，请把 127.0.0.1、localhost 加入代理排除（NO_PROXY），否则本机 HTTP 流量可能被代理拦截。

托盘应用操作

环境变量覆盖（可选）

IMAGE_MCP_API_BASE / IMAGE_MCP_API_KEY / IMAGE_MCP_MODEL 优先级高于 config.json，适合不想把密钥写入配置文件时使用。

常见问题排查

「多模态 API 返回内容为空」（或报错信息含模型名 + 原始响应）

新版错误信息会自带模型名、截断的原始响应和排查提示，例如：

多模态 API 返回内容为空（模型 mimo-v2.5）。原始响应：{"error": {...}}。请检查模型 ID 是否正确，详情见 imagemcp.log

按顺序排查：

AI 不用 MCP，反而用自己视觉/Read 工具看图

这是全局规则没生效。检查：

1. 让 AI 重新按第 3 步安装（粘贴 ai_rules/IMAGE_RULES.md 内容给它）；

2. 确认你所在 agent 的全局规则文件（Claude Code → ~/.claude/CLAUDE.md， opencode → ~/.config/opencode/AGENTS.md，其他 agent 见提示词中的自查表） 已包含「ImageMCP 图片识别规则」段落（含 <!-- ImageMCP-rules-start --> 标记）；

3. 修改全局规则后需要重启 agent（新会话生效）；

4. 确认 MCP 已注册（Claude Code：claude mcp list 应看到 imagemcp）。

其他

日志

程序运行后会在 exe 同目录生成 imagemcp.log，记录每次 analyze_image 调用的输入与输出：

[2026-08-03 22:58:41.172] [OK] analyze_image 耗时2232ms
  输入 image : C:\Users\...\blue.png
  输入 question: 这张图是什么颜色？一句话
  输出        : 这张图是蓝色（纯蓝色）的。

• 包含时间、状态（OK/ERROR）、agent 传入的图片来源与提示词、返回内容、耗时；

• 图片为 base64 data URI 时只记录前缀与长度，避免日志膨胀；

• 自动轮转：单个日志默认超过 5MB 归档为 imagemcp.log.<时间戳>，默认保留 3 份；

• 环境变量控制：

  • IMAGEMCP_LOG=0 关闭日志；

  • IMAGEMCP_LOG_MAX_MB=<数字> 调整单文件上限（MB）；

  • IMAGEMCP_LOG_KEEP=<数字> 调整保留归档份数。

开发者运行（源码方式）

pip install -r requirements.txt
python main.py            # 托盘应用（默认）
python main.py --serve    # stdio MCP 服务（给只支持 stdio 的客户端）
python main.py --http     # headless HTTP 服务（调试用）

二次打包

pip install -r requirements-dev.txt
build.bat                # 产出 dist\imagemcp.exe（已包含 ai_rules 数据）

工作原理

任意 MCP 客户端 ──HTTP──▶ imagemcp.exe (127.0.0.1:9847/mcp) ──HTTP──▶ 多模态 API (MiMo)
                              ▲ 常驻托盘
                              │ 读/写 config.json（与 exe 同目录）

analyze_image 工具接受 image（本地绝对路径 / http(s) URL / base64 data URI）与 question（可选，有默认值），图片统一转为 base64 内联发送，答案直接返回文本模型。限制：单图 ≤ 50MB；支持 JPEG / PNG / GIF / WebP / BMP。