Skip to main content
Glama
Alzeros

readpic-mcp

by Alzeros
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

readpic-mcp

一个 MCP（Model Context Protocol）服务，把图片交给视觉模型分析、返回详细的中文文本描述，让不支持多模态的文本模型也能"看懂"图片。专为软件开发场景设计（截图、UI 设计稿、错误日志、架构图等）。

安装

环境要求：Node.js 18+

# 1. 克隆仓库
git clone git@github.com:Alzeros/readpic-mcp.git
cd readpic-mcp

# 2. 一键安装（安装依赖 → 复制配置模板 → 打印 MCP 配置）
node setup.js

# 3. 编辑配置，填入你的 API 信息
# 用编辑器打开 config.json，修改 api_base_url 和 api_key

安装完成后，将 setup.js 打印的 MCP 配置粘贴到你的 AI 客户端（CodeBuddy/Cursor 等）即可使用。

Related MCP server: MCP Image Recognition Server

配置

复制 config.example.json 为 config.json，填入自建 API 站地址与密钥：

{
  "api_base_url": "https://your-api-server.com/v1/chat/completions",
  "api_key": "your-api-key",
  "model_name": "auto-vl",
  "default_prompt": "",
  "timeout_ms": 30000,
  "max_retries": 2,
  "retry_backoff_ms": 500,
  "max_image_bytes": 5242880,
  "max_image_long_edge": 1568,
  "log_level": "info"
}

配置查找顺序（取第一个存在的）：

  1. 环境变量 READPIC_CONFIG_PATH 指定的路径

  2. 可执行文件（dist/index.js）同目录的 config.json

  3. 进程 cwd 下的 config.json

  4. ~/.readpic/config.json

config.json 已加入 .gitignore。代码容忍 UTF-8 BOM，Windows 编辑器加 BOM 也不影响。

配置项

字段

说明

默认值

api_base_url

API 服务站完整请求地址（OpenAI 兼容）

—

api_key

认证密钥

—

model_name

视觉模型名称

auto-vl

default_prompt

默认分析提示词；留空则用内置（软件开发场景）

内置提示词

timeout_ms

HTTP 请求超时（毫秒）

30000

max_retries

API 失败重试次数

2

retry_backoff_ms

重试退避基数，第 n 次等待 base * 2^(n-1)

500

max_image_bytes

单图原始体积上限（字节），超出触发缩放

5242880

max_image_long_edge

等比缩放长边像素上限

1568

log_level

日志级别 debug/info/warn/error

info

在 CodeBuddy 中注册

设置 → MCP → Add MCP，填入：

{
  "mcpServers": {
    "readpic": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-tool/dist/index.js"],
      "description": "图片识读工具 - 将截图/图片转为详细文本描述"
    }
  }
}

运行 node setup.js 会自动打印好带本机路径的配置，直接复制粘贴即可。

工具：read_picture

参数

类型

必填

说明

image_source

string

否

本地文件路径或图片 URL；为空读取系统剪贴板

prompt

string

否

自定义分析提示词；为空用默认提示词

返回：图片内容的详细中文文本描述（Markdown 分节，与默认提示词的 6 个分节对齐）。

实现说明

  • 图片来源：URL 由 MCP 端下载后转 base64（不依赖 API 站拉取，兼容内网/鉴权图）；本地文件、剪贴板同样转 data URI，请求体结构统一。

  • 缩放：用 sharp 等比缩放到长边 ≤ max_image_long_edge；GIF 取首帧转 PNG；缩放后仍超 max_image_bytes 则报错不发送。

  • 剪贴板：Windows 用 PowerShell（STA 模式 System.Windows.Forms.Clipboard）；macOS 用 pngpaste；Linux 用 xclip。（未使用 clipboard-image，避免不维护的依赖。）

  • API 重试：仅对网络错误 / 5xx / 429 重试（指数退避），4xx（除 429）不重试；错误消息报告实际重试次数。

  • 日志：全部写 stderr（MCP 协议占用 stdout），用 READPIC_LOG_LEVEL 环境变量覆盖级别。

项目结构

mcp-tool/
├── src/
│   ├── index.ts          # MCP Server 入口，注册 read_picture
│   ├── config.ts         # 配置加载（查找路径 + BOM 容忍 + 校验）
│   ├── logger.ts         # 日志（stderr）
│   ├── api-client.ts     # OpenAI 兼容请求 + 重试
│   └── image-loader.ts   # 文件/URL/剪贴板 -> base64 + sharp 缩放
├── config.example.json   # 配置模板
├── package.json
├── tsconfig.json
└── README.md

This server cannot be installed

F
license - not found
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • huuthangntk-claude-vision-mcp-server

    Analyze images from multiple angles to extract detailed insights or quick summaries. Describe visu…

  • Diagrams MCP

    Generate cloud architecture diagrams, flowcharts, and sequence diagrams.

  • Frenchie

    OCR, transcription, file extraction, and image generation for AI agents via MCP.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Alzeros/readpic-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server