# 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
Raw data
{
"_id": null,
"home_page": null,
"name": "mcposprint",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cards, escpos, mcp, printer, server, task, thermal, usb",
"author": "MCPOSprint Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/21/63/6376200beadc25f0e175be83301b56aacb5122e2273ef330dd89c7043ca0/mcposprint-1.0.0.tar.gz",
"platform": null,
"description": "# MCPOSprint - MCP Server for ESC/POS Printing over USB\n\nHi! 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. \n\nThis 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. \n\n## \ud83d\ude80 Installation\n\nMCPOSprint runs directly via `uvx`.\n\n### Prerequisites - Install these first\n- **Python 3.10+**\n- **UV package manager**: Install from [astral.sh/uv](https://astral.sh/uv)\n- **Thermal printer** : ESC/POS compatible USB printer\n- **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)\n- **libusb** for USB printer access\n - macOS: `brew install libusb`\n - Ubuntu/Debian: `sudo apt install libusb-1.0-0-dev`\n\n## Getting Started\n\n1. **Install UV** (if not already installed):\n ```bash\n curl -LsSf https://astral.sh/uv/install.sh | sh\n ```\n\n2. **Configure Your MCP Client** with MCPOSprint (see configuration section below)\n\n\n## \ud83c\udfaf MCP Client Setup\n\n#### Minimal Configuration (Recommended)\n\nYou can add this to the mcp config file of whatever client you use\n\nFor most users, just configure your Notion credentials if you want them:\n\n```json\n{\n \"mcpServers\": {\n \"mcposprint\": {\n \"command\": \"uvx\",\n \"args\": [\"mcposprint\"],\n \"env\": {\n \"PATH\": \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\",\n \"NOTION_API_KEY\": \"your_notion_api_key_here\",\n \"TASKS_DATABASE_ID\": \"your_database_id_here\"\n }\n }\n }\n}\n```\n\n**Default settings used:**\n- **OUTPUT_DIR**: `./images` (saved relative to Claude Desktop's working directory)\n- **PRINTER_NAME**: `EPSON_TM_T20III-17`\n- **CARD_WIDTH/HEIGHT**: `580` pixels (optimized for 58mm thermal printers)\n\n#### Full Configuration (Advanced)\n\nIf you need to override defaults:\n\n```json\n{\n \"mcpServers\": {\n \"mcposprint\": {\n \"command\": \"uvx\", \n \"args\": [\"mcposprint\"],\n \"env\": {\n \"PATH\": \"/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin\",\n \"OUTPUT_DIR\": \"./my-custom-images\",\n \"PRINTER_NAME\": \"YOUR_PRINTER_NAME\",\n \"CARD_WIDTH\": \"580\",\n \"CARD_HEIGHT\": \"580\", \n \"NOTION_API_KEY\": \"your_notion_api_key_here\",\n \"TASKS_DATABASE_ID\": \"your_database_id_here\",\n \"DEBUG\": \"false\"\n }\n }\n }\n}\n```\n\n**Configuration Notes:**\n- **PATH**: Adjust for your system (macOS Homebrew path shown)\n- **OUTPUT_DIR**: Where images are saved (relative to Claude Desktop's working directory)\n- **PRINTER_NAME**: Use your actual thermal printer name\n- **Notion credentials**: Optional - only needed for Notion integration\n\n### Available Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OUTPUT_DIR` | `./images` | Where generated card images are saved |\n| `PRINTER_NAME` | `EPSON_TM_T20III-17` | Your thermal printer name |\n| `CARD_WIDTH` | `580` | Card width in pixels |\n| `CARD_HEIGHT` | `580` | Card height in pixels |\n| `NOTION_API_KEY` | _(none)_ | Your Notion integration API key |\n| `TASKS_DATABASE_ID` | _(none)_ | Your Notion tasks database ID |\n| `DEBUG` | `false` | Enable debug logging |\n\n### Output Directory\n\nGenerated 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.\n\n### Notion Setup\n\n1. Create a Notion integration at https://www.notion.so/my-integrations\n2. Copy the API key to your `.env` file\n3. Share your tasks database with the integration\n4. Copy the database ID to your `.env` file\n\nDatabase should have these properties:\n- **Name** or **Task** (title)\n- **Due Date** (date)\n- **Priority** (select: High, Medium, Low)\n- **Status** (status: Not Started, In Progress, Done)\n- **Description** (rich text, optional)\n\n\n\n### Usage with MCP Clients\n\nOnce connected, you can use these tools in your MCP client:\n\n- **Generate cards from markdown**: Use `process_static_cards` tool\n- **Fetch Notion tasks**: Use `process_notion_tasks` tool (with progress tracking)\n- **Print existing images**: Use `print_only` tool\n- **Test printer**: Use `test_printer_connection` tool\n- **Run diagnostics**: Use `run_diagnostics` tool\n- **Get printer specs**: Access `image://thermal-card-size` resource\n\n### Markdown Format\n\n```markdown\n## Morning Routine\n- *Get dressed\n- Brush teeth\n- Make coffee\n- Check calendar\n\n## Work Tasks\n- *Review emails\n- Update project status\n- *Prepare for 2pm meeting\n- Submit timesheet\n```\n\n- Use `## Title` for card headers\n- Use `- Task` for regular tasks\n- Use `- *Task` for priority tasks (marked with \u2605)\n\n### Development Installation (Optional)\n\nOnly needed for contributing or customization:\n\n```bash\n# Clone the repository \ngit clone https://github.com/your-username/mcposprint.git\ncd mcposprint\n\n# Install with uv\nuv sync\n\n# Start the MCP server\nuv run mcposprint\n```\n\n## \ud83d\udd27 MCP Tools\n\nMCPOSprint provides 6 MCP tools for task card generation and printing:\n\n### Available Tools\n\n1. **`process_static_cards`** - Generate cards from markdown files\n - Parameters: `file` (string), `no_print` (boolean)\n - Returns: List of generated file paths\n\n2. **`process_notion_tasks`** - Fetch and process Notion tasks (with progress tracking)\n - Parameters: `no_print` (boolean)\n - Returns: List of generated file paths\n - Features: Real-time progress updates via Context\n\n3. **`print_only`** - Print existing image files from directory\n - Parameters: `directory` (string)\n - Returns: Success status message\n\n4. **`test_printer_connection`** - Test thermal printer connectivity\n - Returns: Connection status message\n\n5. **`run_diagnostics`** - Run comprehensive system diagnostics\n - Returns: Detailed diagnostic information\n\n6. **`create_sample_files`** - Generate sample markdown file for testing\n - Returns: Success status message\n\n### MCP Resources\n\n- **`image://thermal-card-size`** - Thermal printer card specifications\n - Width: 384 pixels (48mm at 203 DPI)\n - Height: Variable (200-400 pixels)\n - Format: PNG, monochrome\n\n## \ud83d\udda8\ufe0f Printer Setup\n\n### Supported Printers\n\n#### AI Generated List of ESC/POS Compatible Thermal Printers\n- **EPSON**: TM-T20III, TM-T88V, TM-T82, TM-T70\n- **Star Micronics**: TSP143, TSP654, TSP100\n- **Citizen**: CT-S310II, CT-S4000\n- **Most USB thermal printers** supporting ESC/POS protocol\n\n### Printer Setup via MCP Tools\n\nUse the MCP tools to test and configure your printer:\n\n```\n# Test printer connection\nUse: test_printer_connection\n\n# Run full diagnostics\nUse: run_diagnostics\n```\n\n## Architecture\n\nThe MCP server is modularized into clean components:\n\n```\nmcposprint/\n\u251c\u2500\u2500 core/\n\u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u2514\u2500\u2500 printer.py # Main orchestration class\n\u251c\u2500\u2500 parsers/\n\u2502 \u251c\u2500\u2500 markdown.py # Markdown file parser\n\u2502 \u2514\u2500\u2500 notion.py # Notion API integration\n\u251c\u2500\u2500 generators/\n\u2502 \u2514\u2500\u2500 card.py # PIL-based card image generation\n\u2514\u2500\u2500 printers/\n \u2514\u2500\u2500 escpos_printer.py # ESC/POS direct USB interface\n```\n\n\n\n## \ud83d\udd0d Troubleshooting\n\n### Common Issues\n\n1. **Printer not found**\n - Use the `test_printer_connection` MCP tool\n - Use the `run_diagnostics` MCP tool for detailed information\n - Check USB connections and printer power\n\n2. **Notion connection fails**\n - Use the `run_diagnostics` MCP tool to verify API configuration\n - Check that your API key is valid in `.env`\n - Verify database permissions in Notion\n - Ensure the database ID is correct\n\n3. **MCP Server connection issues**\n - Verify the server is running: `uv run mcposprint`\n - Check your MCP client configuration\n - Ensure the working directory path is correct\n\n### Real-time Progress Tracking\n\nThe `process_notion_tasks` tool provides real-time progress updates:\n- \u2705 API Success: Found X tasks\n- Processing task 1/3: Task Name\n- \u2705 Generated: ./output/file.png\n- \u2705 Print Success: Task Name\n\nThis prevents client timeouts during long operations.\n\n## Development\n\n### Local Development\n```bash\n# Install in development mode with dev dependencies\nuv sync --all-extras\n\n# Run tests (when available)\npytest\n\n# Format code\nblack mcposprint/\nisort mcposprint/\n\n# Type checking\nmypy mcposprint/\n```\n\n### Running the MCP Server\n```bash\n# Start the server for development\nuv run mcposprint\n\n# Test with MCP inspector (if available)\n# Connect your MCP client to localhost\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Changelog\n\n### v1.0.0 - MCPOSprint Initial Release\n- \u2705 Full MCP server implementation with 6 tools\n- \u2705 Real-time progress tracking with Context support\n- \u2705 Async Notion task processing with timeout handling\n- \u2705 Thermal printer card generation and printing\n- \u2705 Static markdown card processing\n- \u2705 Modular architecture with clean separation\n- \u2705 Environment-based configuration\n- \u2705 ESC/POS direct USB printing support\n- \u2705 QR code generation for Notion tasks\n- \u2705 Comprehensive error handling and diagnostics\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for thermal printer task card generation",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/bhandzo/mcposprint#readme",
"Homepage": "https://github.com/bhandzo/mcposprint",
"Issues": "https://github.com/bhandzo/mcposprint/issues",
"Repository": "https://github.com/bhandzo/mcposprint"
},
"split_keywords": [
"cards",
" escpos",
" mcp",
" printer",
" server",
" task",
" thermal",
" usb"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c006fd53ffa996e3a8ce5428278a062a3031f2b7111d4a45161743b46fed221a",
"md5": "13c983113cf137b46830e0ba3dc126e2",
"sha256": "c0019d18ca87f8787134bafa28efedbfcd85cf834b30426a4455a2769457159f"
},
"downloads": -1,
"filename": "mcposprint-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "13c983113cf137b46830e0ba3dc126e2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 24480,
"upload_time": "2025-10-18T00:00:40",
"upload_time_iso_8601": "2025-10-18T00:00:40.408482Z",
"url": "https://files.pythonhosted.org/packages/c0/06/fd53ffa996e3a8ce5428278a062a3031f2b7111d4a45161743b46fed221a/mcposprint-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "21636376200beadc25f0e175be83301b56aacb5122e2273ef330dd89c7043ca0",
"md5": "057860125e33cd2c115c1b8c053c421e",
"sha256": "8540a6285118183d9721bf1742cc7a8f41d4e5b05461d7f1e57dd7891c63042e"
},
"downloads": -1,
"filename": "mcposprint-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "057860125e33cd2c115c1b8c053c421e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 84290,
"upload_time": "2025-10-18T00:00:41",
"upload_time_iso_8601": "2025-10-18T00:00:41.598409Z",
"url": "https://files.pythonhosted.org/packages/21/63/6376200beadc25f0e175be83301b56aacb5122e2273ef330dd89c7043ca0/mcposprint-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-18 00:00:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bhandzo",
"github_project": "mcposprint#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcposprint"
}
JSON
