MCPOSprint

# MCPOSprint - MCP Server for ESC/POS Printing over USB Hi! This escalated quickly and became a whole thing. Full disclosure, AI helped me write a lot of this code, but I've tested it pretty throughly on a mac to confirm it works. This is a uv based MCP that lets you connect an MCP client to a usb connected ESC/POS printer. It has baked in tools for printing your tasks from notion with QR codes, and a template to print out markdown tasklists, as well as a generic print image tool you can use to print arbitrary images. I've only tested it with an EPSON_TM_T20III-17, so YMMV with other ESC/POS printers. ## 🚀 Installation MCPOSprint runs directly via `uvx`. ### Prerequisites - Install these first - **Python 3.10+** - **UV package manager**: Install from [astral.sh/uv](https://astral.sh/uv) - **Thermal printer** : ESC/POS compatible USB printer - **Notion API Token** (optional): If you want to print tasks from Notion. [You can see how to generate a token in Notion's docs](https://developers.notion.com/docs/authorization#set-up-the-auth-flow-for-a-public-integration) - **libusb** for USB printer access - macOS: `brew install libusb` - Ubuntu/Debian: `sudo apt install libusb-1.0-0-dev` ## Getting Started 1. **Install UV** (if not already installed): ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. **Configure Your MCP Client** with MCPOSprint (see configuration section below) ## 🎯 MCP Client Setup #### Minimal Configuration (Recommended) You can add this to the mcp config file of whatever client you use For most users, just configure your Notion credentials if you want them: ```json { "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" } } } } ``` **Default settings used:** - **OUTPUT_DIR**: `./images` (saved relative to Claude Desktop's working directory) - **PRINTER_NAME**: `EPSON_TM_T20III-17` - **CARD_WIDTH/HEIGHT**: `580` pixels (optimized for 58mm thermal printers) #### Full Configuration (Advanced) If you need to override defaults: ```json { "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" } } } } ``` **Configuration Notes:** - **PATH**: Adjust for your system (macOS Homebrew path shown) - **OUTPUT_DIR**: Where images are saved (relative to Claude Desktop's working directory) - **PRINTER_NAME**: Use your actual thermal printer name - **Notion credentials**: Optional - only needed for Notion integration ### Available Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `OUTPUT_DIR` | `./images` | Where generated card images are saved | | `PRINTER_NAME` | `EPSON_TM_T20III-17` | Your thermal printer name | | `CARD_WIDTH` | `580` | Card width in pixels | | `CARD_HEIGHT` | `580` | Card height in pixels | | `NOTION_API_KEY` | _(none)_ | Your Notion integration API key | | `TASKS_DATABASE_ID` | _(none)_ | Your Notion tasks database ID | | `DEBUG` | `false` | Enable debug logging | ### Output Directory Generated card images are saved to the `OUTPUT_DIR` (default: `./images`) relative to Claude Desktop's working directory. The directory is created automatically if it doesn't exist. ### Notion Setup 1. Create a Notion integration at https://www.notion.so/my-integrations 2. Copy the API key to your `.env` file 3. Share your tasks database with the integration 4. Copy the database ID to your `.env` file Database should have these properties: - **Name** or **Task** (title) - **Due Date** (date) - **Priority** (select: High, Medium, Low) - **Status** (status: Not Started, In Progress, Done) - **Description** (rich text, optional) ### Usage with MCP Clients Once connected, you can use these tools in your MCP client: - **Generate cards from markdown**: Use `process_static_cards` tool - **Fetch Notion tasks**: Use `process_notion_tasks` tool (with progress tracking) - **Print existing images**: Use `print_only` tool - **Test printer**: Use `test_printer_connection` tool - **Run diagnostics**: Use `run_diagnostics` tool - **Get printer specs**: Access `image://thermal-card-size` resource ### Markdown Format ```markdown ## Morning Routine - *Get dressed - Brush teeth - Make coffee - Check calendar ## Work Tasks - *Review emails - Update project status - *Prepare for 2pm meeting - Submit timesheet ``` - Use `## Title` for card headers - Use `- Task` for regular tasks - Use `- *Task` for priority tasks (marked with ★) ### Development Installation (Optional) Only needed for contributing or customization: ```bash # 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 Tools MCPOSprint provides 6 MCP tools for task card generation and printing: ### Available Tools 1. **`process_static_cards`** - Generate cards from markdown files - Parameters: `file` (string), `no_print` (boolean) - Returns: List of generated file paths 2. **`process_notion_tasks`** - Fetch and process Notion tasks (with progress tracking) - Parameters: `no_print` (boolean) - Returns: List of generated file paths - Features: Real-time progress updates via Context 3. **`print_only`** - Print existing image files from directory - Parameters: `directory` (string) - Returns: Success status message 4. **`test_printer_connection`** - Test thermal printer connectivity - Returns: Connection status message 5. **`run_diagnostics`** - Run comprehensive system diagnostics - Returns: Detailed diagnostic information 6. **`create_sample_files`** - Generate sample markdown file for testing - Returns: Success status message ### MCP Resources - **`image://thermal-card-size`** - Thermal printer card specifications - Width: 384 pixels (48mm at 203 DPI) - Height: Variable (200-400 pixels) - Format: PNG, monochrome ## 🖨️ Printer Setup ### Supported Printers #### AI Generated List of ESC/POS Compatible Thermal Printers - **EPSON**: TM-T20III, TM-T88V, TM-T82, TM-T70 - **Star Micronics**: TSP143, TSP654, TSP100 - **Citizen**: CT-S310II, CT-S4000 - **Most USB thermal printers** supporting ESC/POS protocol ### Printer Setup via MCP Tools Use the MCP tools to test and configure your printer: ``` # Test printer connection Use: test_printer_connection # Run full diagnostics Use: run_diagnostics ``` ## Architecture The MCP server is modularized into clean components: ``` 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 ``` ## 🔍 Troubleshooting ### Common Issues 1. **Printer not found** - Use the `test_printer_connection` MCP tool - Use the `run_diagnostics` MCP tool for detailed information - Check USB connections and printer power 2. **Notion connection fails** - Use the `run_diagnostics` MCP tool to verify API configuration - Check that your API key is valid in `.env` - Verify database permissions in Notion - Ensure the database ID is correct 3. **MCP Server connection issues** - Verify the server is running: `uv run mcposprint` - Check your MCP client configuration - Ensure the working directory path is correct ### Real-time Progress Tracking The `process_notion_tasks` tool provides real-time progress updates: - ✅ API Success: Found X tasks - Processing task 1/3: Task Name - ✅ Generated: ./output/file.png - ✅ Print Success: Task Name This prevents client timeouts during long operations. ## Development ### Local Development ```bash # 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/ ``` ### Running the MCP Server ```bash # Start the server for development uv run mcposprint # Test with MCP inspector (if available) # Connect your MCP client to localhost ``` ## License MIT License - see LICENSE file for details. ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## Changelog ### v1.0.0 - MCPOSprint Initial Release - ✅ Full MCP server implementation with 6 tools - ✅ Real-time progress tracking with Context support - ✅ Async Notion task processing with timeout handling - ✅ Thermal printer card generation and printing - ✅ Static markdown card processing - ✅ Modular architecture with clean separation - ✅ Environment-based configuration - ✅ ESC/POS direct USB printing support - ✅ QR code generation for Notion tasks - ✅ Comprehensive error handling and diagnostics