MCPOSprint-用于通过USB进行ESC/POS打印的MCP服务器
嗨！这件事很快升级成了一件大事。完全披露，人工智能帮助我编写了很多这样的代码，但我已经在mac上对其进行了相当彻底的测试，以确认其有效。
这是一个基于紫外线的MCP，允许您将MCP客户端连接到usb连接的ESC/POS打印机。它内置了使用二维码打印任务的工具，以及打印标记任务列表的模板，以及可用于打印任意图像的通用打印图像工具。我只用EPSON_TM_T20III-17测试过它，所以YMMV用其他ESC/POS打印机测试过。
🚀 安装
MCPOSprint直接通过以下方式运行 uvx.
先决条件-先安装这些
- Python 3.10+
- UV包管理器：从安装 星光sh/uv
- 热敏打印机 ：ESC/POS兼容USB打印机
- 通知API令牌 （可选）：如果您想从Notion打印任务。 您可以在Notion的文档中看到如何生成令牌
- libusb 用于USB打印机访问
- macOS： brew install libusb - Ubuntu/Debian： sudo apt install libusb-1.0-0-dev
入门指南
- 安装UV （如果尚未安装）：
curl -LsSf https://astral.sh/uv/install.sh | sh- 配置您的MCP客户端 使用MCPOSprint（见下面的配置部分）
🎯 MCP客户端设置
最小配置（推荐）
您可以将其添加到您使用的任何客户端的mcp配置文件中
对于大多数用户，如果需要，只需配置您的Notion凭据：
{
"mcpServers": {
"mcposprint": {
"command": "uvx",
"args": ["mcposprint"],
"env": {
"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
"NOTION_API_KEY": "your_notion_api_key_here",
"TASKS_DATABASE_ID": "your_database_id_here"
}
}
}
}使用的默认设置：
- OUTPUT_DIR:
./images（相对于Claude Desktop的工作目录保存） - 打印机名称:
EPSON_TM_T20III-17 - 卡片宽度/高度:
580像素（针对58mm热敏打印机进行了优化）
完整配置（高级）
如果需要覆盖默认值：
{
"mcpServers": {
"mcposprint": {
"command": "uvx",
"args": ["mcposprint"],
"env": {
"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
"OUTPUT_DIR": "./my-custom-images",
"PRINTER_NAME": "YOUR_PRINTER_NAME",
"CARD_WIDTH": "580",
"CARD_HEIGHT": "580",
"NOTION_API_KEY": "your_notion_api_key_here",
"TASKS_DATABASE_ID": "your_database_id_here",
"DEBUG": "false"
}
}
}
}配置说明：
- 路径：根据您的系统进行调整（显示的是macOS Homebrew路径）
- OUTPUT_DIR：保存图像的位置（相对于Claude Desktop的工作目录）
- 打印机名称：使用您实际的热敏打印机名称
- 通知凭据：可选-仅Notion集成需要
可用环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
OUTPUT_DIR | ./images | 生成的卡片图像保存在哪里 |
PRINTER_NAME | EPSON_TM_T20III-17 | 您的热敏打印机名称 |
CARD_WIDTH | 580 | 卡片宽度（像素） |
CARD_HEIGHT | 580 | 卡片高度（像素） |
NOTION_API_KEY | _（无）_ | 您的Notion集成API密钥 |
TASKS_DATABASE_ID | _（无）_ | 您的Notion任务数据库ID |
DEBUG | false | 启用调试日志记录 |
输出目录
生成的卡图像保存到 OUTPUT_DIR （默认值： ./images)相对于Claude Desktop的工作目录。如果目录不存在，则会自动创建。
概念设置
- 在以下位置创建Notion集成https://www.notion.so/my-integrations
- 将API密钥复制到
.env文件 - 通过集成共享您的任务数据库
- 将数据库ID复制到您的
.env文件
数据库应具有以下属性：
- 名字 或 任务 （标题）
- 截止日期 （日期）
- 优先级 （选择：高、中、低）
- 状态 （状态：未开始、正在进行、已完成）
- 描述 （富格文本，可选）
与MCP客户端一起使用
连接后，您可以在MCP客户端中使用这些工具：
- 从markdown生成卡片：使用
process_static_cards工具 - 获取Notion任务：使用
process_notion_tasks工具（带进度跟踪） - 打印现有图像：使用
print_only工具 - 测试打印机：使用
test_printer_connection工具 - 运行诊断程序：使用
run_diagnostics工具 - 获取打印机规格：访问
image://thermal-card-size资源
Markdown格式
## Morning Routine
- *Get dressed
- Brush teeth
- Make coffee
- Check calendar
## Work Tasks
- *Review emails
- Update project status
- *Prepare for 2pm meeting
- Submit timesheet- 使用
## Title用于卡头 - 使用
- Task用于常规任务 - 使用
- *Task对于优先级任务（标记为★)
开发安装（可选）
仅用于贡献或定制：
# Clone the repository
git clone https://github.com/your-username/mcposprint.git
cd mcposprint
# Install with uv
uv sync
# Start the MCP server
uv run mcposprint🔧 MCP工具
MCPOSprint提供6个MCP工具用于任务卡生成和打印：
可用工具
process_static_cards-从markdown文件生成卡片
- 参数： file （字符串）， no_print （布尔值） - 返回：生成的文件路径列表
process_notion_tasks-获取和处理Notion任务（带进度跟踪）
- 参数： no_print （布尔值） - 返回：生成的文件路径列表 - 功能：通过Context实时更新进度
print_only-从目录打印现有图像文件
- 参数： directory （字符串） - 返回：成功状态消息
test_printer_connection-测试热敏打印机连接
- 返回：连接状态消息
run_diagnostics-运行全面的系统诊断
- 返回：详细的诊断信息
create_sample_files-生成用于测试的示例markdown文件
- 返回：成功状态消息
MCP资源
image://thermal-card-size-热敏打印机卡规格
- 宽度：384像素（203 DPI时为48毫米） - 高度：可变（200-400像素） - 格式：PNG，单色
🖨️ 打印机设置
支持的打印机
人工智能生成的ESC/POS兼容热敏打印机列表
- 爱普生：TM-T20III、TM-T88V、TM-T82、TM-T70
- Star Micronics：TSP143、TSP654、TSP100
- 公民：CT-S310II、CT-S4000
- 大多数USB热敏打印机 支持ESC/POS协议
通过MCP工具设置打印机
使用MCP工具测试和配置打印机：
# Test printer connection
Use: test_printer_connection
# Run full diagnostics
Use: run_diagnostics建筑
MCP服务器被模块化为干净的组件：
mcposprint/
├── core/
│ ├── config.py # Configuration management
│ └── printer.py # Main orchestration class
├── parsers/
│ ├── markdown.py # Markdown file parser
│ └── notion.py # Notion API integration
├── generators/
│ └── card.py # PIL-based card image generation
└── printers/
└── escpos_printer.py # ESC/POS direct USB interface🔍 故障排除
常见问题
- 找不到打印机
- 使用 test_printer_connection MCP工具 - 使用 run_diagnostics MCP工具获取详细信息 - 检查USB连接和打印机电源
- 通知连接失败
- 使用 run_diagnostics 用于验证API配置的MCP工具 - 检查您的API密钥在中是否有效 .env - 在Notion中验证数据库权限 - 确保数据库ID正确
- MCP服务器连接问题
- 验证服务器是否正在运行： uv run mcposprint - 检查您的MCP客户端配置 - 确保工作目录路径正确
实时进度跟踪
这 process_notion_tasks 该工具提供实时进度更新：
- ✅ API成功：找到X个任务
- 处理任务1/3：任务名称
- ✅ 生成时间：。/输出/file.png
- ✅ 打印成功：任务名称
这可以防止在长时间操作期间客户端超时。
发展
地方发展
# Install in development mode with dev dependencies
uv sync --all-extras
# Run tests (when available)
pytest
# Format code
black mcposprint/
isort mcposprint/
# Type checking
mypy mcposprint/运行MCP服务器
# Start the server for development
uv run mcposprint
# Test with MCP inspector (if available)
# Connect your MCP client to localhost许可证
MIT许可证-有关详细信息，请参阅许可证文件。
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
更新日志
v1.0.0-MCPOSprint初始版本
- ✅ 使用6个工具全面实施MCP服务器
- ✅ 支持Context的实时进度跟踪
- ✅ 异步Notion任务处理与超时处理
- ✅ 热敏打印机卡生成和打印
- ✅ 静态标记卡处理
- ✅ 模块化架构，分离清晰
- ✅ 基于环境的配置
- ✅ ESC/POS直接USB打印支持
- ✅ Notion任务的二维码生成
- ✅ 全面的错误处理和诊断