内容
# 打印机MCP服务器
[模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，通过CUPS使AI助手能够在Linux/macOS系统上控制打印机。
透過 MCP 協議讓 AI 助手控制印表機，支援列印檔案、測試頁、查詢狀態、取消工作等操作。
## 前置需求
### 1. CUPS 打印系统
本服务器依赖 CUPS 打印系统的命令行工具（`lp`、`lpstat`、`cancel`）。大多数 Linux 发行版和 macOS 都预装了 CUPS。
**检查 CUPS 是否已安装 / 確認 CUPS 是否已安裝：**
```bash
lpstat -v
```
如果找不到该命令，请安装 CUPS：
```bash
# Debian / Ubuntu
sudo apt install cups
# Fedora / RHEL
sudo dnf install cups
# Arch Linux
sudo pacman -S cups
# macOS — CUPS is included by default
```
### 2. 至少需要設定一台印表機
**这是必要条件。** MCP 服务器通过 CUPS 控制打印机，如果系统中没有設定任何打印机，所有工具都无法正常运作。
**检查是否已設定印表機 / 確認是否已設定印表機：**
```bash
lpstat -a
```
如果没有列出打印机，您需要添加一台。以下是常见方法：
**方法 A：图形界面（推荐桌面用户）**
- 打开 **设置 → 打印机** （GNOME）或 **系统设置 → 打印机** （KDE）
- 点击“添加打印机”并按照向导进行操作
**方法 B：命令行**
```bash
# 1. 查找网络上的可用打印机
lpinfo -v
# 2. 查找匹配的驱动程序
lpinfo --make-and-model "YOUR_PRINTER_BRAND" -m
# 3. 添加打印机
sudo lpadmin -p PRINTER_NAME -E \
-v "DEVICE_URI_FROM_STEP_1" \
-m "DRIVER_PATH_FROM_STEP_2"
# 4. 设置为默认打印机（可选）
sudo lpadmin -d PRINTER_NAME
```
**示例 — 添加 Ricoh 网络打印机：**
```bash
sudo lpadmin -p MP-C2004ex -E \
-v "dnssd://RICOH%20MP%20C2004ex._pdl-datastream._tcp.local/" \
-m "openprinting-ppds:0/ppd/openprinting/Ricoh/PDF/Ricoh-MP_C2004ex_PDF.ppd"
sudo lpadmin -d MP-C2004ex
```
**验证打印机是否正常 / 驗證印表機是否正常：**
```bash
echo "test" | lp
```
## 安装
### 使用 uv（推荐）
```bash
uv pip install printer-mcp
```
### 使用 pip
```bash
pip install printer-mcp
```
## 配置
### Claude Code
将以下内容添加到您的 Claude Code MCP 设置（`~/.claude/mcp.json` 或项目 `.mcp.json`）：
```json
{
"mcpServers": {
"printer": {
"command": "uvx",
"args": ["printer-mcp"]
}
}
}
```
### Claude Desktop
将以下内容添加到您的 Claude Desktop 配置（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"printer": {
"command": "uvx",
"args": ["printer-mcp"]
}
}
}
```
### 直接运行
```bash
# 使用 uv
uv run printer-mcp
# 使用 python
python server.py
```
## 可用工具
| 工具 | 描述 | 說明 |
|------|-------------|------|
| `list_printers` | 列出所有可用的打印机 | 列出所有可用的印表機 |
| `print_test_page` | 打印测试页以验证打印机连接 | 列印測試頁以驗證印表機連線 |
| `print_file` | 打印文件，可选择打印机和份数设置 | 列印指定檔案，可選擇印表機及份數 |
| `printer_status` | 查询打印机状态和打印队列 | 查詢印表機狀態與列印佇列 |
| `cancel_job` | 取消指定或所有打印工作 | 取消指定或所有列印工作 |
### 工具参数
**`print_file`**
- `file_path`（必填）— 要打印的文件路径。支持的格式：PDF、文本和图像文件（PNG、JPG、JPEG、GIF、BMP、TIFF、WebP — 图像会自动转换为PDF后再打印）
- `printer`（可选）— 打印机名称，默认为系统默认打印机
- `copies`（可选）— 份数，默认为1
- `page_size`（可选）— 纸张大小，默认为 `A4`。选项：`A3`、`A4`、`A5`、`B4`、`B5`、`Letter`、`Legal`、`Tabloid`
- `orientation`（可选）— 打印方向，默认为 `portrait`。选项：`portrait`、`landscape`
- `color_mode`（可选）— 色彩模式，默认为 `gray`（灰度）。选项：`gray`、`color`
**`print_test_page`**
- `printer`（可选）— 打印机名称，默认为系统默认打印机
- `page_size`（可选）— 纸张大小，默认为 `A4`。选项：`A3`、`A4`、`A5`、`B4`、`B5`、`Letter`、`Legal`、`Tabloid`
- `orientation`（可选）— 打印方向，默认为 `portrait`。选项：`portrait`、`landscape`
- `color_mode`（可选）— 色彩模式，默认为 `gray`（灰度）。选项：`gray`、`color`
**`printer_status`**
- `printer`（可选）— 打印机名称，留空以查询所有打印机
**`cancel_job`**
- `job_id`（可选）— 要取消的任务ID，留空以取消所有任务
## 使用示例
配置完成后，您可以询问您的AI助手：
```
"打印文件 /home/user/report.pdf"
"列出可用打印机"
"打印 invoice.pdf 的 3 份到 HP 打印机"
"打印机状态如何？"
"取消所有打印任务"
"打印测试页"
```
## 支持的平台
- **Linux** — 任何已安装 CUPS 的发行版
- **macOS** — CUPS 已内置
> **注意：** Windows 不受支持。Windows 原生不支持 CUPS。
## 故障排除
| 问题 | 解决方案 |
|---------|----------|
| `lpstat: No destinations added` | 没有配置打印机。请参见上面的[前置需求](#2-至少需要設定一台印表機)。 |
| `lp: command not found` | CUPS 未安装。请参见 [CUPS 安装](#1-cups-打印系统)。 |
| 打印任务已发送但未打印 | 检查 `printer_status` 中的错误。验证打印机是否在线并已连接。 |
| 权限被拒绝 | 您的用户可能需要加入 `lpadmin` 组：`sudo usermod -aG lpadmin $USER` |
| 图像文件无法打印 | 图像文件（PNG、JPG 等）通过 Pillow 自动转换为 PDF。确保已安装 `Pillow`：`pip install Pillow` |
## License
MIT
