内容
# 扫描器MCP
> **让Claude扫描和阅读纸质文档**，来自任何USB或网络扫描器。
<p align="center">
<img src="https://raw.githubusercontent.com/AminHA1248/scanner-mcp/main/docs/demo.gif" alt="让Claude扫描文档；它调用scan_document工具并读取页面" width="760">
</p>
一个 **通用的MCP服务器**，为Claude（和其他MCP客户端）提供扫描工具。它通过标准的 **eSCL / AirScan / Mopria** 协议与 **网络扫描器**配合使用，通过平台驱动程序堆栈与 **USB扫描器**配合使用 - **WIA** 在Windows上，**SANE** 在Linux / macOS上。无需厂商特定的驱动程序代码。
当Claude需要读取纸质文档时，它可以调用 `scan_document`，然后页面图像直接内联返回，以便Claude可以直接读取（可选地识别为文本或保存为PDF）。
## 暴露的功能
| 工具 | 目的 |
|------|---------|
| `list_scanners` | 发现从此机器可访问的每个扫描器（网络+USB）。 |
| `scan_document` | 扫描页面/堆栈并将其作为内联图像、保存的文件和/或OCR文本返回。 |
后端会自动检测并优雅地降级 - 相同的服务器在任何操作系统上运行，并激活它可以访问的扫描器：
- **eSCL** (`_uscan._tcp` mDNS) - 无驱动的网络MFP/扫描器。*跨平台。*
- **WIA** - Windows上的USB（和一些网络）扫描器，通过PowerShell COM驱动。
- **TWAIN** - 仅在Windows上暴露TWAIN数据源的扫描器（较旧/专业设备，无可用的WIA驱动程序）。可选；需要`pytwain` + TWAIN DSM（见下文）。
- **SANE** (`scanimage`) - Linux和macOS上的USB/网络扫描器。
## 安装
```bash
pip install scanner-mcp
# 可选的OCR支持（还需要安装Tesseract二进制文件）：
pip install "scanner-mcp[ocr]"
# 可选的TWAIN后端，仅限Windows（还需要TWAIN DSM，见下文）：
pip install "scanner-mcp[twain]"
```
<details>
<summary>或从源代码安装（用于开发）</summary>
```bash
git clone https://github.com/AminHA1248/scanner-mcp
cd scanner-mcp
python -m venv .venv
# Windows： .venv\Scripts\activate
# macOS/Linux： source .venv/bin/activate
pip install -e ".[twain]" # 可编辑安装；如果需要OCR，请添加[ocr]
```
</details>
平台先决条件：
- **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无需额外操作。
- **网络扫描器**：只需在同一LAN/子网中；mDNS处理发现。
## 连接到Claude
### Claude Desktop - 一键式扩展（最简单）
从
[最新版本](https://github.com/AminHA1248/scanner-mcp/releases/latest)下载`scanner-mcp-<version>.mcpb`，并通过**设置 → 扩展 → 安装扩展…**打开它。 需要Python 3.10+，并使用
`pip install scanner-mcp`（扩展程序会告知您是否缺少）。 详情：
[docs/EXTENSION.md](docs/EXTENSION.md)。
### Claude Desktop - 手动配置
编辑`claude_desktop_config.json`（设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"scanner": {
"command": "scanner-mcp"
}
}
}
```
如果找不到`scanner-mcp`（其Scripts/bin目录不在Claude的PATH中），请使用启动器的完整路径 - 例如Windows上的`C:\Users\you\...\Scripts\scanner-mcp.exe`或macOS/Linux上的`/path/to/venv/bin/scanner-mcp` - 或`python -m scanner_mcp.server`.
### Claude 代码（CLI）
```bash
claude mcp add scanner -- scanner-mcp
```
重启客户端，然后询问Claude：*“列出我的扫描仪”* 或 *“扫描玻璃上的文档并读取它。”*
## 您实际上如何运行它
您通常 **不需要自己启动任何程序** - Claude Desktop/Code在后台启动
`scanner-mcp`服务器（根据上面的配置），并在您请求时调用其工具。手动运行`scanner-mcp`只是启动MCP服务器，它会默默地等待stdin上的JSON-RPC；它不是交互式shell。
要在 **没有Claude的情况下**测试硬件，请使用捆绑的CLI，[`test_scan.py`](test_scan.py)：
```bash
# 从项目文件夹，使用venv的Python
python test_scan.py --list # 发现扫描仪
python test_scan.py --dpi 300 # 扫描（如果只有一个，则自动选择）
python test_scan.py --scanner "<id>" --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** 涵盖了过去~10年内销售的大多数扫描仪（任何“AirPrint/AirScan”或“Mopria”功能的设备）。较旧的仅USB扫描仪通过WIA/SANE进行。
- 使用Pillow组装多页WIA扫描的PDF输出。
- HTTPS eSCL设备使用自签名证书，因此为它们禁用TLS验证（LAN扫描仪的典型做法）；请优先使用受信任的网络。
- 本服务器仅执行本地硬件I/O - 它不会将任何内容发送到云。
## 隐私政策
scanner-mcp完全在您的机器上运行，**不收集任何数据** - 没有遥测，没有分析，没有扫描的网络传输。扫描文件仅保存到您的本地磁盘（默认`~/Scans`）并返回给您请求的MCP客户端。完整政策：
**[PRIVACY.md](https://github.com/AminHA1248/scanner-mcp/blob/main/PRIVACY.md)**。
## 许可证
MIT
