Skip to main content
Glama
MCPOSprint
by bhandzo

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

Related MCP server: Printer AI MCP

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

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

  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

  • 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

  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

# 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

  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

Available Tools

7 tools
create_sample_filesA

Generate a sample markdown file to test MCPOSprint functionality.

Creates 'sample_cards.md' in the current directory with example task lists formatted for MCPOSprint. Perfect for testing your setup or learning the markdown format before creating your own task lists.

Returns: Success message confirming file creation

Generated file includes: - Multiple task sections (Morning, Work, Evening) - Examples of priority tasks (marked with *) - Proper formatting with ## headers and - bullets

Use the generated file with process_static_cards tool to test printing. Configuration is handled via environment variables in your MCP client.

Inputs: no named parameters. Returns: result

infoA

Get MCPOSprint server information and system status.

Returns version, dependency status, configuration issues, and operational health. Essential for troubleshooting and verifying proper setup.

Returns: System information including version, dependencies, and configuration status

Checks include: - Server version and build information - Required system dependencies (libusb, PIL, etc.) - Environment variable configuration - Log file accessibility - Basic printer connectivity

Inputs: no named parameters.

run_diagnosticsA

Perform comprehensive system diagnostics for MCPOSprint setup.

Runs a complete health check of your MCPOSprint installation, including configuration validation, printer connectivity, Notion API access, and system dependencies. Essential for troubleshooting setup issues.

Returns: Detailed diagnostic report as JSON object

Diagnostic checks include: - Environment variable configuration - Printer detection and connection - Notion API authentication and database access - Python package dependencies - Output directory permissions - System library availability (libusb, PIL, etc.)

Use this when: - Setting up MCPOSprint for the first time - Troubleshooting printing or Notion connection issues - Verifying configuration after changes

Inputs: no named parameters.

task_cards_from_notionA

Fetch today's tasks from Notion and generate thermal printer cards with QR codes.

Connects to your Notion database, retrieves tasks with status "Today" or "In Progress", generates individual task cards with QR codes linking back to Notion, and optionally prints them. Provides real-time progress updates to prevent client timeouts.

Requires NOTION_API_KEY and TASKS_DATABASE_ID environment variables.

Args: no_print: If True, only generate images without printing (default: False)

Returns: List of generated PNG file paths

Progress tracking includes: - API connection status - Task fetching progress - Individual card generation - Print success/failure for each card

Inputs: no_print. Returns: result

test_printer_connectionA

Verify that your thermal printer is connected and responding.

Attempts to establish a USB connection to your ESC/POS thermal printer and sends a basic test command. Use this to troubleshoot connection issues before printing actual content.

Returns: Success/failure message with connection status

Checks: - USB device detection - ESC/POS command response - Printer initialization

If this fails, check: - Printer is powered on - USB cable is connected - PRINTER_NAME environment variable matches your device - libusb is installed on your system

Inputs: no named parameters. Returns: result

todo_list_cards_from_markdownA

Generate and optionally print task cards from a markdown file.

Parses a markdown file with task lists (using ## headers and - bullets), generates PNG images for each section, and optionally sends them to your thermal printer. Priority tasks marked with * get a star symbol.

Args: file: Path to markdown file (relative to current directory) no_print: If True, only generate images without printing (default: False)

Returns: List of generated PNG file paths

Example markdown format: ## Morning Tasks - *Get dressed (priority) - Brush teeth - Make coffee

Inputs: file (required), no_print. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: create_sample_files generates test files, info provides system status, print_only handles existing images, run_diagnostics performs health checks, task_cards_from_notion fetches from Notion, test_printer_connection verifies printer connectivity, and todo_list_cards_from_markdown processes markdown files. The descriptions reinforce these unique functions, making tool selection straightforward for an agent.

    Naming Consistency4/5

    The tools follow a consistent snake_case pattern throughout, with clear verb_noun structures (e.g., create_sample_files, test_printer_connection). However, there is a minor deviation with 'info' being a single noun instead of a verb_noun pair, which slightly breaks the pattern but does not significantly impact readability or predictability.

    Tool Count5/5

    With 7 tools, the count is well-scoped for the MCPOSprint server's purpose of managing task cards and printer operations. Each tool serves a specific role in the workflowβ€”from setup and diagnostics to fetching tasks and printingβ€”without redundancy, making the set efficient and focused.

    Completeness4/5

    The tool set covers the core workflows comprehensively: creating test files, system diagnostics, printer testing, fetching tasks from Notion, processing markdown, and printing. A minor gap exists in lacking a dedicated tool for updating or deleting generated files or cards, but agents can work around this using system commands or the existing tools for reprinting or regeneration.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that enables AI assistants to control and monitor Klipper 3D printers via the Moonraker API. It supports comprehensive printer management, including G-code execution, toolchanger operations, and real-time status monitoring.
      29
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A cross-platform MCP server that enables AI assistants to manage printers, query printer status, and print files on Windows, macOS, and Linux.
      14
      -
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for printing POS receipts via CUPS printers, supporting a two-step confirmation flow with preview.
      1
      14 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Personal Notion MCP server with tools for task management, wrapping the Notion REST API to create, query, and update tasks in a kanban board.
      -