AminHA1248/scanner-mcp
GitHub: AminHA1248/scanner-mcp
该项目是一个将网络和 USB 扫描仪能力暴露给 Claude 等 MCP 客户端的通用 MCP 服务器，让 AI 助手能直接扫描并读取纸质文档。
Stars: 0 | Forks: 0
# scanner-mcp
一个**通用的 MCP 服务器**，它向 Claude（以及任何其他 MCP
客户端）暴露了一个扫描工具。它通过标准的 **eSCL / AirScan /
Mopria** 协议支持**网络扫描仪**，并通过平台驱动程序栈支持 **USB 扫描仪** —
Windows 上使用 **WIA**，Linux/macOS 上使用 **SANE**。不需要特定于供应商的驱动代码。
当 Claude 需要读取纸质文档时，它可以调用 `scan_document`，页面
图像将以内联方式返回，以便 Claude 直接读取（可选择 OCR 转换为文本，或
保存为 PDF）。
## 它暴露的内容
| 工具 | 用途 |
|------|---------|
| `list_scanners` | 发现本机可访问的所有扫描仪（网络 + USB）。 |
| `scan_document` | 扫描单页/多页并将其作为内联图像、已保存的文件和/或 OCR 文本返回。 |
后端会被自动检测并平滑降级 —— 同一个服务器可以在任何操作系统上运行，并
启用它能访问到的任何扫描仪：
- **eSCL** (`_uscan._tcp` mDNS) —— 免驱动的网络 MFP/扫描仪。*跨平台。*
- **WIA** —— **Windows** 上的 USB（以及部分网络）扫描仪，通过 PowerShell COM 驱动。
- **TWAIN** —— 仅暴露 TWAIN 数据源的 Windows 扫描仪（没有可用 WIA 驱动的较老/专业设备
）。可选；需要 `pytwain` + 一个 TWAIN DSM（见下文）。
- **SANE** (`scanimage`) —— **Linux** 和 **macOS** 上的 USB/网络扫描仪。
## 安装
```
cd scanner-mcp
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e .
# 可选的 OCR 支持：
pip install -e ".[ocr]" # also needs the Tesseract binary installed
# 可选的 TWAIN 后端（仅限 Windows）：
pip install -e ".[twain]" # also needs a TWAIN DSM (see below)
```
平台前提条件：
- **Windows**：WIA 不需要额外安装任何东西 —— 它和 PowerShell 都是 Windows 内置的。请安装
扫描仪的正常 Windows 驱动程序，使其出现在*设备*中。
- **TWAIN（可选）**：安装 `pytwain`（`pip install -e ".[twain]"`）并确保存在
TWAIN **DSM**。64 位 Python 需要 `TWAINDSM.dll`（由大多数 TWAIN
2.x 驱动程序或 TWAIN DSM 可再发行组件提供）；32 位 Python 可以使用经典的
`twain_32.dll`。如果两者都未安装，TWAIN 后端只会保持禁用状态。
- **Linux**：`sudo apt install sane-utils`（提供 `scanimage`）。
- **macOS**：运行 `brew install sane-backends` 以支持 USB；网络扫描仪通过 eSCL 工作，无需额外组件。
- **网络扫描仪**：只需在同一局域网/子网内；mDNS 负责发现。
## 将其连接到 Claude
### Claude Desktop
编辑 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置）：
```
{
"mcpServers": {
"scanner": {
"command": "C:\\Users\\aminh\\scanner-mcp\\.venv\\Scripts\\scanner-mcp.exe"
}
}
}
```
在 macOS/Linux 上使用 venv 路径 `/path/to/scanner-mcp/.venv/bin/scanner-mcp`。
### Claude Code (CLI)
```
claude mcp add scanner -- /path/to/scanner-mcp/.venv/bin/scanner-mcp
```
重启客户端，然后询问 Claude：*“列出我的扫描仪”*或*“扫描玻璃板上的文档并读取它。”*
## 实际运行方式
通常您**不需要自己启动任何东西** —— Claude Desktop/Code 会在
后台启动 `scanner-mcp` 服务器（根据上述配置），并在您询问时调用其工具。
手动运行 `scanner-mcp` 只是启动了 MCP 服务器，它会在 stdin 上静默等待
JSON-RPC；它不是交互式 shell。
要在**不使用 Claude** 的情况下测试硬件，请使用附带的 CLI [`test_scan.py`](test_scan.py)：
```
# 从项目文件夹中，使用 venv 的 Python
python test_scan.py --list # discover scanners
python test_scan.py --dpi 300 # scan (auto-selects if only one)
python test_scan.py --scanner "
" --source adf --format pdf
```
## 配置（环境变量）
| 变量 | 默认值 | 含义 |
|----------|---------|---------|
| `SCANNER_MCP_SAVE_DIR` | `~/Scans` | 扫描文件的写入位置。 |
| `SCANNER_MCP_LOG` | `INFO` | 日志级别。 |
## `scan_document` 选项
`scanner_id`（来自 `list_scanners`；如果只有一个则自动选择），`source`
（`auto`/`platen`/`adf`/`adf-duplex`），`resolution` (DPI)，`color_mode`
（`color`/`gray`/`lineart`），`output_format`（`png`/`jpeg`/`pdf`），`save_dir`，
`return_image`（供 Claude 读取的内联图像），`ocr`（提取文本）。
## 注意事项与限制
- **eSCL** 支持过去十年中销售的大多数扫描仪（任何支持“AirPrint/AirScan”
或“Mopria”的设备）。较旧的纯 USB 设备则通过 WIA/SANE 处理。
- 多页 WIA 扫描的 PDF 输出是使用 Pillow 拼接的。
- HTTPS eSCL 设备使用自签名证书，因此对它们禁用了 TLS 验证
（这对于局域网扫描仪很典型）；建议使用受信任的网络。
- 此服务器仅执行本地硬件 I/O —— 它不会向云端发送任何内容。
## 许可证
MIT标签：AI合规, eSCL, MCP服务器, SANE, WIA, 文档扫描, 硬件接口, 逆向工具