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
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
libusb for USB printer access
- macOS: brew install libusb
- Ubuntu/Debian: sudo apt install libusb-1.0-0-dev

Getting Started

Install UV (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

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:

{
  "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:

{
  "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

Create a Notion integration at https://www.notion.so/my-integrations
Copy the API key to your .env file
Share your tasks database with the integration
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

## 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:

# 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

process_static_cards - Generate cards from markdown files
- Parameters: file (string), no_print (boolean)
- Returns: List of generated file paths
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
print_only - Print existing image files from directory
- Parameters: directory (string)
- Returns: Success status message
test_printer_connection - Test thermal printer connectivity
- Returns: Connection status message
run_diagnostics - Run comprehensive system diagnostics
- Returns: Detailed diagnostic information
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

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
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
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

# 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

# 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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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