MCPOSprint MCP Server

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

1. Install UV (if not already installed):

   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:

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

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

## 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
• U