MCPOSprint
Provides direct USB printing support for Epson ESC/POS compatible thermal printers to output generated task cards, images, and diagnostic reports.
Allows generating and printing formatted task cards from markdown files, supporting headers for card titles and specific syntax for priority tasks.
Enables fetching tasks from Notion databases to generate and print task cards, supporting task properties like priority, status, and due dates, along with QR code generation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCPOSprint Print my Notion tasks for today with QR codes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 libusbUbuntu/Debian:
sudo apt install libusb-1.0-0-dev
Related MCP server: Printer AI MCP
Getting Started
Install UV (if not already installed):
curl -LsSf https://astral.sh/uv/install.sh | shConfigure 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-17CARD_WIDTH/HEIGHT:
580pixels (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 |
|
| Where generated card images are saved |
|
| Your thermal printer name |
|
| Card width in pixels |
|
| Card height in pixels |
| (none) | Your Notion integration API key |
| (none) | Your Notion tasks database ID |
|
| 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
.envfileShare your tasks database with the integration
Copy the database ID to your
.envfile
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_cardstoolFetch Notion tasks: Use
process_notion_taskstool (with progress tracking)Print existing images: Use
print_onlytoolTest printer: Use
test_printer_connectiontoolRun diagnostics: Use
run_diagnosticstoolGet printer specs: Access
image://thermal-card-sizeresource
Markdown Format
## Morning Routine
- *Get dressed
- Brush teeth
- Make coffee
- Check calendar
## Work Tasks
- *Review emails
- Update project status
- *Prepare for 2pm meeting
- Submit timesheetUse
## Titlefor card headersUse
- Taskfor regular tasksUse
- *Taskfor 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 filesParameters:
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 directoryParameters:
directory(string)Returns: Success status message
test_printer_connection- Test thermal printer connectivityReturns: Connection status message
run_diagnostics- Run comprehensive system diagnosticsReturns: Detailed diagnostic information
create_sample_files- Generate sample markdown file for testingReturns: Success status message
MCP Resources
image://thermal-card-size- Thermal printer card specificationsWidth: 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_diagnosticsArchitecture
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_connectionMCP toolUse the
run_diagnosticsMCP tool for detailed informationCheck USB connections and printer power
Notion connection fails
Use the
run_diagnosticsMCP tool to verify API configurationCheck that your API key is valid in
.envVerify database permissions in Notion
Ensure the database ID is correct
MCP Server connection issues
Verify the server is running:
uv run mcposprintCheck 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 localhostLicense
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
Available Tools
7 toolscreate_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.
print_onlyA
Send existing image files to the thermal printer without regenerating them.
Scans a directory for PNG/JPG image files and sends them directly to your thermal printer. Useful for reprinting previously generated cards or printing custom images you've created.
Args: directory: Path to directory containing image files
Returns: Success message with count of printed images
Supported formats: PNG, JPG, JPEG Images are printed in alphabetical order with automatic paper cutting.
Inputs: directory (required). Returns: result
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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server β exposes tasks, projects, messages, and files as tools for AI agents.
Thermal label MCP server: render, validate, debug and convert ZPL, EPL, TSPL and CPCL labels.
Screenshots, PDFs, image editing, QR codes, email validation and more through one hosted MCP server.
Remote MCP server for notes, tasks, kanban boards and docs - the Slates agentic workspace
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceAn 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-
- FlicenseNot gradedqualityDmaintenanceA cross-platform MCP server that enables AI assistants to manage printers, query printer status, and print files on Windows, macOS, and Linux.14-
- AlicenseAqualityDmaintenanceMCP server for printing POS receipts via CUPS printers, supporting a two-step confirmation flow with preview.114 npmMIT
- FlicenseNot gradedqualityDmaintenancePersonal Notion MCP server with tools for task management, wrapping the Notion REST API to create, query, and update tasks in a kanban board.-