MCPOSprint

You run an MCP server that connects an MCP client to a USB ESC/POS printer, enabling automated card printing and Notion task support from a single, configurable workflow. It includes tools to generate cards from markdown, fetch Notion tasks, print images, test printers, and run diagnostics, all while targeting common 58mm thermal printers via ESC/POS over USB.

How to use

To use this MCP server, connect your MCP client to the local MCP server and load your configuration. You can generate cards from markdown files, fetch tasks from Notion, print existing images, test printer connectivity, and run diagnostics to troubleshoot any issues. Real-time progress updates are available when processing Notion tasks, helping you monitor long-running operations without timeouts.

How to install

Prerequisites you need before starting are:

• Python 3.10+
• UV package manager
• A USB ESC/POS printer compatible with USB
• libusb for USB access
• Notion API token (optional, for Notion task printing)
• A supported Operating System with USB access to the printer Install UV if it is not already present on your system.

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

# Start the MCP server for development or local usage
uv run mcposprint

Configure the MCP client to connect to this server and tailor environment variables for your setup. The following minimal configuration example shows how to enable Notion-based task printing and point to your Notion credentials and database.

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

Additional setup and configuration

You can override defaults to customize output location, card dimensions, and printer selection. See the configuration notes and environment variable list for details.

Notion setup

If you want to print tasks from Notion, create a Notion integration, obtain an API key, share your tasks database with the integration, and copy the database ID into your environment variables. The integration enables the process_notion_tasks tool to fetch and format tasks into printable cards with optional progress updates.

Usage with MCP Clients

Once connected, you can use the following tools within your MCP client to generate and print cards, or to test and diagnose the printer setup.

Markdown and card format

Cards are authored in markdown with headers and task items. Use a header like ## Morning Routine and list tasks with normal or priority indicators. The tool converts markdown into printable, monochrome card images sized for your printer.

Development installation (optional)

If you contribute or customize, you can clone the project and install via the MCP workflow.

# 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

Troubleshooting

If you encounter printer not found or Notion authorization issues, run diagnostics to gather details, verify USB connections, and confirm API keys and database IDs. Use the dedicated tools to test printer connectivity and to diagnose broader MCP server health.

Notes on architecture and components

The server is organized into a modular structure that handles configuration, markdown parsing, Notion integration, card generation, and the USB ESC/POS printer interface. This separation allows you to customize or extend any part of the workflow without impacting other components.

Available tools

process_static_cards

Generate cards from markdown files. Takes a file path and an option to skip printing, returning a list of created file paths.

process_notion_tasks

Fetch and process Notion tasks with progress tracking. Returns a list of generated file paths and provides real-time context updates.

print_only

Print existing image files from a specified directory. Returns a status message indicating success or failure.

test_printer_connection

Test thermal printer connectivity and verify a usable print path.

run_diagnostics

Run a full set of system diagnostics and return detailed information for troubleshooting.

create_sample_files

Generate sample markdown files for testing card generation and printing.