内容
<div align="center">
# 图片阅读器 MCP
<p align="center">
<img src="https://mark.sylphx.com/api/v1/banner?type=holo&theme=tokyonight&text=image+reader+mcp&desc=Evidence-first+image+reading+for+AI+agents+%E2%80%94+metadata%2C+OCR+text%2C+regions%2C+and+ci&height=200&animation=rise&credit=0" alt="image-reader-mcp — Sylphx Mark banner" width="100%" />
</p>
### 您的智能代理是否看到了真相？
基于证据的图片阅读，适用于 AI 智能代理。一次调用可以将任何本地图片转换为**智能媒体双胞胎** —— 尺寸、元数据、带有边界框的可选 OCR 文本和可引用的信任警告，无需询问视觉 LLM 进行猜测。
[](https://www.npmjs.com/package/@sylphx/image-reader-mcp)
[](https://opensource.org/licenses/MIT)
[](https://github.com/SylphxAI/image-reader-mcp/actions/workflows/ci.yml)
[](https://www.typescriptlang.org/)
**本地优先** · **一次智能 `read_image` 调用** · **带有边界框和来源的证据** · **23 项测试**
SOTA 家族路线图：[docs/roadmap/sota-family-roadmap.md](docs/roadmap/sota-family-roadmap.md)。
[⭐ 给这个仓库点赞](https://github.com/SylphxAI/image-reader-mcp) 如果智能代理应该用事实而不是视觉模型猜测来读取图片。
· [快速开始](#快速开始) · [查看其工作原理](#查看其工作原理) · [为什么不使用视觉 LLM 猜测？](#为什么不使用视觉LLM猜测)
Sylphx 阅读器产品组合的一部分 —— 智能阅读器 MCP 位于 [smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp)。
</div>
---
## 问题
图片不仅仅是文件名。它们是像素、EXIF、方向、嵌入的 GPS、隐藏的元数据和只有通过 OCR 才能提取的文本，附带几何信息。
大多数智能代理堆栈通过 **视觉 LLM** 读取图片，并获得一个看似合理的描述。尺寸被四舍五入。OCR 文本被改述。元数据消失。引用变成“模型这么说”。然后智能代理开始臆想 —— 自信地。
**图片阅读器 MCP 是为智能代理需要关于图片的可衡量事实而构建的，而不是创造性描述。**
## 为什么不使用视觉 LLM 猜测？
| 典型的视觉路径 | 图片阅读器 MCP |
| --- | --- |
| “描述这张图片” | 返回文件名、MIME 类型、尺寸和结构化元数据 |
| 改述的 OCR 文本 | 可选的 Tesseract 文本，带有边界框和置信度 |
| GPS 和 EXIF 泄露到上下文中 | GPS 信息被删除；对可疑元数据的信任警告 |
| 没有来源 | 带有可衡量、可引用的字段的智能媒体双胞胎 JSON |
| 默认云 API | **本地优先** —— 在您的机器上使用 sharp + exifr |
| 交付即使用 | **23** 个单元测试，涵盖模式、元数据、OCR 钩子、安全限制、医生和发布门控 |
## 查看其工作原理
**安装一次。调用一次。**
```bash
claude mcp add image-reader -- npx @sylphx/image-reader-mcp
```
```json
{
"path": "/absolute/path/to/photo.jpg",
"include_metadata": true,
"include_ocr": true
}
```
`read_image` 在本地检查文件并返回智能媒体双胞胎 —— 无需生成式 LLM：
```json
{
"filename": "photo.jpg",
"mime": "image/jpeg",
"dimensions": { "width": 4032, "height": 3024 },
"orientation": 1,
"metadata": {
"Make": "ExampleCamera",
"Model": "Pro X",
"DateTimeOriginal": "2026-03-15T14:22:10"
},
"ocr": {
"available": true,
"lines": [
{
"text": "INVOICE #1042",
"bbox": { "x": 120, "y": 48, "width": 310, "height": 36 },
"confidence": 92
}
]
},
"trust_warnings": []
}
```
缩略的形状 —— 如果未安装 Tesseract，则可选的 OCR 会跳过。
## MCP 工具界面
| 工具 | 使用场景 |
| --- | --- |
| `read_image` | 读取本地图片并返回尺寸、MIME 类型、元数据、可选的 OCR 文本和信任警告。 |
支持的格式：PNG、JPEG、GIF、WebP、TIFF 和其他 sharp 可以解码的格式。
## 快速开始
### Claude 代码
```bash
claude mcp add image-reader -- npx @sylphx/image-reader-mcp
```
### Claude 桌面版
将以下内容添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"image-reader": {
"command": "npx",
"args": ["@sylphx/image-reader-mcp"]
}
}
}
```
### 任意 MCP 客户端
```bash
npx @sylphx/image-reader-mcp
```
需要 Node.js `>=22.13`。可选的 OCR 使用本地 Tesseract 适配器（如果安装了的话）—— 默认情况下不需要云凭证。
## 安全模型
- **本地优先** —— `read_image` 在本地机器上解析路径；默认情况下不使用云视觉 API。
- **GPS 信息删除** —— 除非明确选择，否则位置元数据将从面向智能代理的输出中删除。
- **尺寸和格式限制** —— 过大或不支持的输入将返回结构化错误，而不是部分猜测。
- **可选 OCR** —— 如果安装了 Tesseract，则会在本地运行；如果没有安装，则会报告为 `available: false`，而不是静默失败。
- **信任警告** —— 可疑的 EXIF、方向或元数据异常会在 `trust_warnings` 中显示，供智能代理验证。
## 发布证明
声明由 CI `benchmark:release-gate` 和发布的路径矩阵（Rust 默认路由，没有遗留 Node 引擎在主要工具上）支持。
```bash
bun run benchmark:release-gate
```
产物：`benchmark-artifacts/image_reader_release_gate.json` —— 必须报告 `status: passed` 才能发布。
## 开发
```bash
git clone https://github.com/SylphxAI/image-reader-mcp.git
cd image-reader-mcp
bun install
bun run build
bun test
bun run doctor
bun run benchmark:release-gate
```
有用的检查：
```bash
bun run check
bun run typecheck
bun run validate
bun run benchmark:release-gate
```
示例 `read_image` 请求位于 [`examples/`](examples/) 中。
## 支持
- [问题](https://github.com/SylphxAI/image-reader-mcp/issues)
- [npm 包](https://www.npmjs.com/package/@sylphx/image-reader-mcp)
- 产品组合编排：[smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp)
## 帮助更多开发者使用
如果视觉模型猜测浪费了您的上下文、引用或对智能代理输出的信任，您就是这个项目面向的对象。
**[⭐ 给这个仓库点赞](https://github.com/SylphxAI/image-reader-mcp)** —— 这是帮助更多智能代理开发者找到基于证据的图片阅读的最快方式。在您的 MCP 客户端设置、团队 Wiki 或智能代理堆栈 README 中分享它。
### 发现（进行中）
| 频道 | 状态 |
| --- | --- |
| [Glama MCP 目录](https://glama.ai/mcp/servers/SylphxAI/image-reader-mcp) | 已列出 — [声明服务器](https://glama.ai/mcp/servers/SylphxAI/image-reader-mcp/admin) 以实现完全可发现性 |
| [官方 MCP 注册表](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.SylphxAI/image-reader-mcp) | 已列出 — `io.github.SylphxAI/image-reader-mcp` @ v0.1.0 |
| [TensorBlock MCP 索引 PR #1113](https://github.com/TensorBlock/awesome-mcp-servers/pull/1113) | 已打开 — 多媒体/文档处理列表 |
| [MCP 服务器社区问题 #4500](https://github.com/modelcontextprotocol/servers/issues/4500) | 已打开 — 社区服务器亮点 |
| [mcp.so 列表问题 #3068](https://github.com/chatmcp/mcpso/issues/3068) | 已打开 — 目录提交请求 |
| [mcpservers.org 提交](https://mcpservers.org/submit) | 尚未列出 — 免费的网络表单提交 |
了解其他 MCP 目录？ [打开一个问题](https://github.com/SylphxAI/image-reader-mcp/issues/new) 并附上链接。
## 许可证
MIT © [SylphxAI](https://github.com/SylphxAI)
