What This Project Does

cat-mcp exposes three MCP tools:

• print_image
• print_text
• print_jira_ticket

It is designed for cat-style BLE thermal printers and includes an embedded printer runtime under src/cat_mcp/catprinter.

Why I Built It

Real-world use case behind this repo:

• I bought a cheap BLE thermal printer and reverse engineered behavior from the Android app.
• I connected it to my poke agent workflow so important events can be printed physically.

In short: my agents can now talk through thermal paper.

Requirements

• Python 3.10+
• Bluetooth enabled host
• Supported cat thermal printer powered on

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

Run Server

stdio mode:

cat-mcp-server

HTTP mode:

cat-mcp-http --host 0.0.0.0 --port 8000

HTTP mode with persistent BLE connection:

cat-mcp-http \
  --host 0.0.0.0 \
  --port 8000 \
  --persistent-connection \
  --connect-on-start \
  --start-device PD01

Default streamable HTTP endpoint:

http://127.0.0.1:8000/mcp

MCP Client Example

{
  "mcpServers": {
    "cat-mcp": {
      "command": "/absolute/path/to/.venv/bin/cat-mcp-server"
    }
  }
}

Tool Summary

print_image: Print an image with configurable binarization and thermal energy.

print_text: Render text to 384px thermal bitmap and print.

print_jira_ticket: Render and print a Jira-style ticket template for assignments.

Scripts Folder Note

Files under scripts are helper utilities for local testing, manual debugging, and demo flows. They are not required to run the packaged server commands.

Example Jira helper:

python scripts/print_jira_ticket_pd01.py \
  --ticket-key MCP-42 \
  --summary "Add printer retry logic" \
  --assignee "calgan" \
  --status "To Do" \
  --priority "High" \
  --ticket-url "https://jira.local/browse/MCP-42"

macOS BLE Note

If first connection fails, grant Bluetooth permission to the host process in System Settings and ensure the printer is discoverable.

Thanks

Thanks to rbaron/catprinter for foundational reverse engineering work that helped this project. I adapted and ported relevant parts into this MCP server for the current Bleak-based flow. For original project details and license text, see:

• https://github.com/rbaron/catprinter