print-mcp

"We absolutely need to bring ink and paper into this."

print-mcp is a home-network print service that turns Markdown into a print-ready PDF and sends it to your network printer. Run it on any Linux machine on the same home network as the printer, optionally open it to the internet with a Cloudflare Tunnel, and give the MCP endpoint to all of your agents.

Your agent can then:

• Use the network printer configured for your home.
• Print Markdown with page size, margins, orientation, copies, duplex, and color options.
• Check the status of a submitted print job.

The important part: the printer stays on your home network and is never exposed to the internet. Cloudflare only provides the secure public connection to the MCP endpoint; the server renders and submits the job through the network printer.

How It Works

                          Cloudflare Tunnel
                         (outbound connection)
                                |
Any MCP client  ------------>  MCP server  ------------>  CUPS  ------------>  Local printer
                                |                         |
                         Markdown -> PDF            USB or IPP

The Docker Compose stack runs three services:

• mcp is the MCP server. It renders Markdown and exposes the tools.
• cups manages the local printer queue and submits print jobs.
• cloudflared is optional. It publishes mcp through a Cloudflare named tunnel without opening an inbound port.

What You Need

• A Linux machine that can reach your home network printer.
• Docker Engine and the Docker Compose plugin.
• A network printer that supports IPP Everywhere, or a USB printer.
• For remote agents: a Cloudflare account, a domain on Cloudflare, and a named tunnel.

Docker Desktop is not supported. USB passthrough and host networking differ from the Linux setup this project expects.

Quick Start

1. Configure the server

git clone <your-repo-url> print-mcp
cd print-mcp
cp .env.example .env

Generate secrets and put them in .env:

openssl rand -hex 32  # MCP_BEARER_TOKEN
openssl rand -hex 24  # CUPS_ADMIN_PASSWORD

At minimum, set these values:

MCP_BEARER_TOKEN=your-long-random-token
CUPS_ADMIN_PASSWORD=your-long-random-password

2. Configure your network printer

For a modern network printer, add its IP address to .env:

CUPS_PRINTER_IP=192.168.1.50
CUPS_PRINTER_NAME=office-printer

When the stack starts, CUPS creates an IPP Everywhere queue at ipp://192.168.1.50/ipp/print, enables it, and makes it the default printer.

If you do not want automatic setup, leave CUPS_PRINTER_IP empty and add a queue manually:

docker compose exec cups lpadmin \
  -p office-printer \
  -E \
  -v ipp://192.168.1.50/ipp/print \
  -m everywhere
docker compose exec cups lpadmin -d office-printer

For a USB printer, use the USB Compose overlay instead:

docker compose -f compose.yaml -f compose.usb.yaml up -d --build

3. Start and test locally

docker compose up -d --build
curl -fsS http://127.0.0.1:8000/healthz

The local endpoints are:

• MCP: http://127.0.0.1:8000/mcp
• CUPS admin: http://127.0.0.1:631/admin

Send a local test print:

echo 'Hello from print-mcp.' | docker compose exec -T mcp \
  python /app/cli/print_file.py -

At this point, print-mcp is running on your home network and can print to the configured network printer. Any MCP client on the same network can use the local endpoint; agents outside your network can use the Cloudflare URL from the next section.

Connect A Remote Agent

To let an MCP client connect from anywhere, put the local MCP endpoint behind a Cloudflare Tunnel.

1. Create the Cloudflare route

In Cloudflare Zero Trust:

1. Create a named tunnel.
2. Add a public hostname, for example print.example.com.
3. Set its service URL to exactly http://mcp:8000.
4. Copy the tunnel token into .env.

Then add the same public hostname to the MCP host allow-list:

CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoi...
MCP_ALLOWED_HOSTS=print.example.com

The hostname must match exactly. If it does not, the tunnel can be healthy while the MCP server rejects requests with HTTP 421 Invalid Host header.

2. Start the tunnel

docker compose --profile tunnel up -d --build

Your MCP endpoint is now:

https://print.example.com/mcp

The tunnel makes an outbound connection from your machine to Cloudflare. You do not need to expose port 8000 or open an inbound firewall port.

3. Add it to your MCP client

Configure your MCP-compatible agent or client with the public URL and the same bearer token from .env:

URL:   https://print.example.com/mcp
Token: MCP_BEARER_TOKEN

The standard authentication header is:

Authorization: Bearer YOUR_MCP_BEARER_TOKEN

For older MCP agents that cannot set an authorization header, use the same token as the final path segment instead:

https://print.example.com/mcp/YOUR_MCP_BEARER_TOKEN

The server treats this URL as an authenticated alias of /mcp. Path tokens can be recorded in proxy, tunnel, browser, or server logs, so prefer the header form when the client supports it.

The exact configuration shape depends on the MCP client. Look for its remote HTTP, Streamable HTTP, or custom MCP server settings.

Now your agent can print.

MCP Tools

The server exposes three tools:

list_printers

Lists configured printers and their current capabilities.

print_markdown

Renders Markdown to PDF and submits it to CUPS. It supports:

• title
• printer
• page_size: letter, legal, or a4
• orientation: portrait or landscape
• margins
• copies: 1 through 10
• sides: one-sided, two-sided long-edge, or two-sided short-edge
• color_mode: auto, color, or monochrome

The default is letter paper, portrait orientation, and two-sided long-edge printing.

get_job_status

Returns the current state and timestamps for a CUPS print job.

Raw HTML is disabled. Markdown images may use public HTTP/HTTPS URLs or data URIs. Private, loopback, link-local, multicast, and reserved destinations are blocked, including after redirects.

Local CLI

The same image includes a CLI for printing without an MCP client:

cat notes.md | docker compose exec -T mcp python /app/cli/print_file.py -

docker compose exec -T mcp python /app/cli/print_file.py notes.md \
  --page-size a4 \
  --orientation portrait \
  --margins-mm 12 \
  --copies 2 \
  --sides two-sided-long-edge \
  --color mono

There is also a host-friendly wrapper for files outside the container:

./bin/print-md.sh --page-size a4 ./docs/report.md

Configuration

Copy .env.example to .env for the complete list. The settings most people need are:

Variable	Purpose
MCP_BEARER_TOKEN	Token required by MCP clients
CUPS_ADMIN_PASSWORD	Password for CUPS administration
CUPS_PRINTER_IP	IP address for automatic IPP queue setup
CUPS_PRINTER_NAME	Name of the automatic CUPS queue
DEFAULT_PRINTER	Queue used when a tool call omits printer
CLOUDFLARE_TUNNEL_TOKEN	Required for the tunnel Compose profile
MCP_ALLOWED_HOSTS	Public hostname accepted by the MCP server

The MCP server and CUPS are bound to localhost by default. Keep them that way when using Cloudflare Tunnel. The tunnel container reaches MCP over the private Compose network.

Troubleshooting

Check service state and logs:

docker compose ps
docker compose logs cups mcp cloudflared

Check the two health endpoints:

curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/readyz

/healthz confirms that the MCP process is running. /readyz is healthy only after CUPS has at least one configured printer.

Common issues:

• HTTP 421 through Cloudflare: add the exact public hostname to MCP_ALLOWED_HOSTS, then recreate the mcp service with docker compose up -d mcp.
• Tunnel is running but the endpoint does not respond: verify the Cloudflare public hostname points to http://mcp:8000 and inspect docker compose logs cloudflared.
• Printer is not found: use the printer's explicit IPP URI. Discovery does not reliably cross Docker or Tailscale networks.
• CUPS keeps crashing with cupsdDoSelect() failed - Bad address!: rebuild the image so the CUPS entrypoint applies the file-descriptor limit workaround.

Development

uv sync --extra dev
uv run ruff check .
uv run pytest
docker compose config