# printer_mcp_server

**Repository Path**: regality/printer_mcp_server

## Basic Information

- **Project Name**: printer_mcp_server
- **Description**: 一个跨系统（Win/Linux/MacOS）的打印机打印的MCP Server Tools，支持指定路径的文件（"txt", "docx", "xlsx", "pptx", "pdf", "md", "jpg", "jpeg", "gif", "png"）打印，也支持大模型输出的直接打印。 
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-08-06
- **Last Updated**: 2025-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

### 跨平台办公文档打印MCP服务工具

支持Windows/Linux/macOS的跨平台打印服务，自动处理文档格式转换和打印参数配置。

### 特性
- 自动识别并转换办公文档（Word/Excel/PowerPoint等）为PDF
- 支持图片文件（JPG/PNG等）直接打印
- 跨平台统一接口，隐藏系统差异
- 详细日志记录和错误处理

### 安装指南

## 1. 系统依赖（Linux）
# Debian/Ubuntu
sudo apt update && sudo apt install -y $(cat system-requirements.txt)

# CentOS/RHEL（需对应替换包名）
sudo yum install -y libreoffice cups ...


## 2.安装Python依赖
pip install -r requirements.txt


#### MCP Server 与 Client 配置
### 一、MCP Server（打印服务端）安装与启动
## 1. 环境准备
操作系统：Windows 10+/Linux (Ubuntu 20.04+/CentOS 8+)/macOS 12+
依赖组件：
Python 3.8+ 及 pip
系统打印服务（Windows Print Spooler / Linux CUPS /macOS 打印服务）
文档转换工具：LibreOffice 7.0+ 或 WPS Office

## 2. 安装步骤
# 1. 克隆仓库
git clone https://github.com/your-username/printer_mcp_server.git
cd printer_mcp_server

# 2. 安装系统依赖（根据系统选择）
# Linux (Debian/Ubuntu)
sudo apt update && sudo apt install -y cups libreoffice libreoffice-calc fonts-wqy-zenhei
sudo systemctl start cups && sudo systemctl enable cups

# Windows
# 手动安装 LibreOffice：https://www.libreoffice.org/download/download/

# macOS
brew install --cask libreoffice

## 3. 安装Python依赖
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows
pip install --upgrade pip
pip install -r requirements.txt

## 3. 启动 Server
# 方式1：Stdio模式（默认，适合本地集成）
python service.py

# 方式2：HTTP模式（支持网络访问）
# python print_service.py --http  # 默认端口6274
# 自定义端口（例如8080）
PROT=9118 python service.py --http

4. 验证 Server 运行
# HTTP模式下检查服务状态
# curl http://localhost:6274/health
curl http://localhost:9118/health # 自定义端口9118
# 成功响应：{"status": "running", "service": "CrossPlatformPrinterService"}


二、MCP Client（Host 端）安装与使用
MCP Client 用于调用 Server 提供的打印接口，支持通过 npx 快速启动，或集成到代码中。

1. 安装 MCP Client 工具
# 无需全局安装，通过npx直接使用
npx @modelcontextprotocol/inspector --version
# 输出版本号即表示可用

2. 连接 Server 并调用接口
方式 1：通过 Inspector 可视化工具（适合调试）
# 连接本地Stdio模式的Server
npx @modelcontextprotocol/inspector python service.py

# 连接HTTP模式的Server（需先启动Server）
# npx @modelcontextprotocol/inspector http://localhost:6274  # 默认端口
npx @modelcontextprotocol/inspector http://localhost:9118  # 自定义端口


启动后会自动打开浏览器，在可视化界面中可直接调用 print_file、list_printers 等接口。

方式 2：通过代码调用（适合集成到业务系统）
安装客户端库：
npm install @modelcontextprotocol/client  # Node.js
# 或 pip install mcp-client  # Python

Node.js 示例：

const { MCP } = require('@modelcontextprotocol/client');

// 连接HTTP模式的Server
const client = new MCP('http://localhost:9118/sse');  # 自定义端口

// 列出可用打印机
async function listPrinters() {
  const printers = await client.call('list_printers');
  console.log('可用打印机:', printers);
}

// 打印文件
async function printDocument() {
  const result = await client.call('print_file', {
    file_path: '/path/to/文档.xlsx',
    printer_name: 'HP LaserJet Pro',
    copies: 2,
    duplex: true
  });
  console.log('打印结果:', result);
}

listPrinters();
printDocument();


Python 示例：

from mcp.client import MCP

# 连接HTTP模式的Server
client = MCP('http://localhost:9118/sse')  # 自定义端口

# 打印文本
response = client.print_text("测试打印", copies=1)
print("文本打印结果:", response)

# 打印文件
response = client.print_file(
  file_path="/path/to/表格.xlsx",
  copies=2,
  color_mode="monochrome"
)
print("文件打印结果:", response)


三、常见问题与调试
1. Server 启动失败
端口占用：更换端口（如 --port 9118），或关闭占用端口的进程：
# Linux/macOS 查找占用6274端口的进程
lsof -i :6274
kill -9 <进程ID>

依赖缺失：根据错误日志安装缺失的系统库或 Python 包。

2. 打印任务无响应
检查打印机是否在线：通过 list_printers 接口确认打印机名称正确。
检查文件权限：确保 Server 有权限读取待打印文件。
查看转换日志：若为 Office 文档，检查 LibreOffice 是否正常工作（日志中搜索 转换输出）。

Client 连接失败
确认 Server 已启动且端口正确。
网络模式下检查防火墙：开放 Server 端口（如 6274）。
查看 Server 日志：HTTP 模式日志默认输出到控制台，Stdio 模式日志需通过 Client 工具查看。

四、部署建议
生产环境：
使用 HTTP 模式启动，配合 Nginx 反向代理和 SSL 加密。
配置系统服务实现开机自启（见上文 “服务管理”）。
定期清理临时文件目录（~/.print_temp）。
多用户场景：
在 Linux 中为打印服务创建专用用户，限制文件系统访问权限。
通过 max_concurrent_jobs 配置限制并发打印任务数。
监控：
集成 Prometheus 监控服务状态（需自行实现指标接口）。
配置日志轮转（如 logrotate）避免日志文件过大。