MCP Printer Server 🖨️

An MCP server for printing documents on macOS/Linux. Provides AI assistants with the ability to print files, manage print queues, and control printers via the CUPS printing system.

Why?

In the era of AI-assisted development, we're generating more documentation, specs, guides, and code than ever before. When working with AI on complex projects, it's often valuable to review generated artifacts offline on paper. This tool makes it effortless to ask your AI assistant: "Print all the markdown files you just created" or "Print the README and all TypeScript files in this directory" — streamlining the workflow from AI generation to offline review.

• Features

• Installation

• Configuration

• Available Tools

• Available Prompts

• Usage Examples

• CUPS Options

• Supported File Types

• Code Rendering

• Troubleshooting

• Security

• Development

• Requirements

• Contributing

Features

• 📄 Print files - PDF, text, and other formats

• 📝 Render markdown - Convert markdown to beautifully formatted PDFs

• 📊 Mermaid diagrams - Flowcharts, sequence diagrams, and more render as visual graphics in markdown

• 💻 Syntax-highlighted code - Automatically render code files with syntax highlighting, line numbers, and proper formatting

• 🔍 Page count preview - Check how many pages a document will print before sending to printer (prevents accidental 200-page printouts!)

• 🖨️ List printers - See all available printers and their status

• 📋 Manage queue - View and cancel print jobs

• ⚙️ Configure - Set default printers

• 🎯 Smart - Supports multiple copies, landscape, duplex, and more

Installation

Add to your MCP configuration file (e.g., ~/.cursor/mcp.json for Cursor):

That's it! The package will be automatically downloaded from npm on first use.

🖥️ Platform Support: This server currently supports macOS and Linux only. Windows is not currently supported (contributions welcome!).

📋 Requirements: Google Chrome or Chromium is required for rendering markdown and code files to PDF. The server will auto-detect Chrome/Chromium installations on macOS/Linux. See Requirements for details.

⚠️ Security: This server allows AI assistants to print files from allowed directories (~/Documents, ~/Downloads, ~/Desktop by default, customizable via MCP_PRINTER_ALLOWED_PATHS). Dotfiles and hidden directories are always blocked. Only use with trusted AI assistants on your local machine. See Security for configuration options.

Configuration

All configuration is optional. Add an env object to customize behavior:

Example configuration:

💡 Note: The MCP_PRINTER_ALLOWED_PATHS example above replaces the default allowed directories. If you set this variable, you must explicitly include any default directories you want to keep (like Documents, Downloads, Desktop) plus any additional directories like your projects folder. Use colon-separated absolute paths (:).

💡 Tip: You can use the list_printers tool to see all available printers and their exact names.

User-specified options in prompts always override these defaults.

Available Tools

get_config

Get the current MCP Printer configuration settings. Only returns non-sensitive configuration values.

Example:

list_printers

List all available printers with their status.

Example:

print_file

Print one or more files to a specified printer. Supports batch operations to reduce tool call costs.

Parameters:

• files (required) - Array of file specifications (use single-element array for one file):

  • file_path (required) - Full path to file

  • printer (optional) - Printer name

  • copies (optional) - Number of copies (default: 1)

  • options (optional) - CUPS options like landscape, sides=two-sided-long-edge

  • skip_confirmation (optional) - Skip page count confirmation check (bypasses MCP_PRINTER_CONFIRM_IF_OVER_PAGES threshold)

  • line_numbers (optional) - Show line numbers when rendering code files (boolean, overrides global setting)

  • color_scheme (optional) - Syntax highlighting theme for code files (e.g., github, monokai, atom-one-light)

  • font_size (optional) - Font size for code files (e.g., 8pt, 10pt, 12pt)

  • line_spacing (optional) - Line spacing for code files (e.g., 1, 1.5, 2)

  • force_markdown_render (optional) - Force markdown rendering to PDF (boolean: true=always render, false=never render, undefined=use config)

  • force_code_render (optional) - Force code rendering to PDF with syntax highlighting (boolean: true=always render, false=never render, undefined=use config)

Note: The code rendering parameters (line_numbers, color_scheme, font_size, line_spacing) only apply when printing code files that are automatically rendered to PDF with syntax highlighting.

Batch Operations: To print multiple files efficiently, pass an array of file specifications. Each file is processed independently, and the operation continues even if individual files fail. The response shows success/failure status for each file.

Batch Size Limit: Batches are limited to 50 items per operation for reliability. If you need to process more items, the AI will automatically split them into multiple tool calls.

Page Count Confirmation: By default, print jobs exceeding 10 physical sheets will trigger a confirmation prompt from the AI before printing. You can adjust this threshold with MCP_PRINTER_CONFIRM_IF_OVER_PAGES or set it to 0 to disable. If you confirm, the AI will automatically retry the print with the confirmation bypassed. This feature only works for PDF files (including auto-rendered markdown and code files).

Example (single file):

Example (batch):

get_page_meta

Get page count and physical sheet information for one or more files before printing. This tool pre-renders files (markdown, code) if needed and returns page metadata. Supports batch operations.

Parameters:

• files (required) - Array of file specifications (use single-element array for one file):

  • file_path (required) - Full path to file

  • options (optional) - CUPS options for duplex detection (e.g., sides=two-sided-long-edge)

  • line_numbers (optional) - Show line numbers when rendering code files (boolean, overrides global setting)

  • color_scheme (optional) - Syntax highlighting theme for code files

  • font_size (optional) - Font size for code files (e.g., 8pt, 10pt, 12pt)

  • line_spacing (optional) - Line spacing for code files (e.g., 1, 1.5, 2)

  • force_markdown_render (optional) - Force markdown rendering to PDF

  • force_code_render (optional) - Force code rendering to PDF with syntax highlighting

Note: Page counting only works for PDF files, including:

• Markdown files (auto-rendered to PDF)

• Code files with syntax highlighting (auto-rendered to PDF)

• Existing PDF files

Plain text files, images, and other non-PDF formats cannot have their page count determined.

Batch Operations: Check page counts for multiple files in a single tool call. Each file is processed independently, and the operation continues even if individual files fail.

Batch Size Limit: Batches are limited to 50 items per operation for reliability. If you need to process more items, the AI will automatically split them into multiple tool calls.

Example (single file):

Example (batch):

Use cases:

• Check page count before printing large documents

• Estimate paper usage for duplex vs single-sided printing

• Preview rendered output of markdown or code files

• Calculate total pages across multiple documents

get_print_queue

Check the print queue for pending jobs.

Parameters:

• printer (optional) - Specific printer to check

Example:

cancel_print_job

Cancel one or more print jobs. Supports batch operations.

Parameters:

• jobs (required) - Array of job cancellation specifications (use single-element array for one job):

  • job_id (optional) - Specific job to cancel

  • printer (optional) - Printer name

  • cancel_all (optional) - Cancel all jobs for printer

Batch Operations: Cancel multiple jobs in a single tool call. Each cancellation is processed independently, and the operation continues even if individual cancellations fail.

Batch Size Limit: Batches are limited to 50 items per operation for reliability. If you need to process more items, the AI will automatically split them into multiple tool calls.

Example (single job):

Example (batch):

get_default_printer

Get the system's default printer (not the MCP_PRINTER_DEFAULT_PRINTER config setting).

Example:

set_default_printer

Set a printer as the default.

Parameters:

• printer (required) - Printer name

Example:

Available Prompts

Prompts are workflow templates that appear as slash commands in your AI assistant (e.g., Cursor). They provide guided workflows for common printing tasks.

/print-changed

Print files that have changed in your git repository for offline review.

What it does:

• Finds files that have changed based on git context (staged, uncommitted, or in a branch)

• Prints all changed files with consistent settings

• Perfect for reviewing code changes on paper before committing or merging

Parameters:

• context - What to print: "staged", "uncommitted", "branch", or a specific branch name

• options (optional) - Print options (e.g., "landscape", "two-sided")

Examples:

Use cases:

• Review staged changes before committing

• Print uncommitted work for offline debugging

• Review all changes in a feature branch

• Create paper copies for code review meetings

Usage Examples

Print Code with Syntax Highlighting

Print Documentation (Batch)

Force Rendering

Print with Options

Manage Queue

Page Count Preview and Confirmation

CUPS Options

Any valid CUPS/lpr options can be passed via the options parameter. Common examples:

• landscape - Print in landscape orientation

• sides=two-sided-long-edge - Double-sided (long edge)

• sides=two-sided-short-edge - Double-sided (short edge)

• page-ranges=1-5 - Print specific pages (e.g., page-ranges=3-5,7,10-12)

• media=Letter or media=A4 - Paper size

• fit-to-page - Scale to fit page

• number-up=2 - Print multiple pages per sheet

Natural Language Requests: Thanks to the flexibility of the underlying CUPS printing system and the AI's knowledge of print options, you don't need to memorize these options. Simply ask naturally—"print pages 3 to 5 in landscape on letter size paper" or "print this double-sided"—and the AI will translate your request into the appropriate CUPS options automatically. Feel free to experiment with common printing scenarios; the AI is smart enough to figure out what you need.

For a complete list of available options:

• Run lpoptions -l in your terminal to see printer-specific options

• See the CUPS documentation for standard printing options

• Check man lpr for command-line options

Supported File Types

The server uses CUPS, which supports:

• ✅ PDF

• ✅ Plain text

• ✅ Images (JPEG, PNG)

• ✅ Markdown

• ✅ Code files (see Code Rendering for details)

• ⚠️ PostScript (printer-dependent - some printers may not support it)

Other document formats may need conversion to PDF first.

Markdown Rendering

Markdown files are rendered to beautifully formatted PDFs using crossnote.

Features

• ✨ Beautiful styling - Clean, modern GitHub-style theme optimized for printing

• 🔢 Automatic page numbers - Every page shows "Page X / Y" at the bottom

• 📊 Mermaid diagrams - Flowcharts, sequence diagrams, class diagrams render as visual graphics

• 🎨 Syntax highlighting - Code blocks within markdown are beautifully highlighted

• ➕ Math rendering - KaTeX support for mathematical expressions

• 📐 Tables & formatting - Table styling, blockquotes, and all standard markdown features

Diagram Support

Markdown rendering includes support for:

• Mermaid - Flowcharts, sequence diagrams, class diagrams, state diagrams, etc.

• WaveDrom - Digital timing diagrams

• GraphViz - Graph visualizations

• Vega & Vega-Lite - Data visualizations

All diagrams render as visual graphics in the PDF output, not code blocks.

Configuration

• To enable/disable markdown rendering: Set MCP_PRINTER_AUTO_RENDER_MARKDOWN to "true" or "false" (default: true)

• To force rendering on a per-call basis: Use the force_markdown_render parameter in print_file

Custom Page Numbering

Page numbers are automatically added to the footer of every rendered markdown PDF. If you want to customize or disable page numbering for a specific file, you can add YAML front-matter:

Or customize the footer template:

Code Rendering

Code files are automatically rendered to PDF with syntax highlighting, line numbers, and proper formatting for optimal printing quality.

Supported Languages

The system uses a strict whitelist approach - only files with recognized extensions or shebangs are automatically rendered as code. This prevents false positives on plain text files like LICENSE or README.

Programming Languages: JavaScript (.js, .jsx), TypeScript (.ts, .tsx), Python (.py), Java (.java), C (.c, .h), C++ (.cpp, .cc, .cxx, .hpp), C# (.cs), Go (.go), Rust (.rs), Swift (.swift), Kotlin (.kt), Ruby (.rb), PHP (.php), Scala (.scala), Perl (.pl, .perl), Lua (.lua), R (.r)

Shell/Scripts: Bash/Shell (.sh, .bash, .zsh, .fish), PowerShell (.ps1), Vim (.vim)

Markup/Data: HTML (.html), CSS (.css), SCSS (.scss), Sass (.sass - uses SCSS highlighting), Less (.less), JSON (.json), YAML (.yaml, .yml), XML (.xml), Markdown (.md), SQL (.sql)

Special Files (no extension): Makefile, Dockerfile, Gemfile, Rakefile, Vagrantfile

Shebang Detection: Files without recognized extensions that contain a shebang (#!/bin/bash, #!/usr/bin/env python3, etc.) in the first 1024 bytes are automatically detected as code. This enables syntax-highlighted rendering of shell scripts and other executable files without extensions.

Unknown Extensions: Files with unknown extensions (like .txt, .bak, .weird) and no shebang will NOT be automatically rendered. To render these files with syntax highlighting, the AI can use the force_code_render=true parameter in the print_file tool call.

💡 Tip: You don't need to know the technical parameter names! Simply ask your AI assistant in natural language: "Print this file and render it as code" or "Make sure to render that shell script with syntax highlighting". The AI will understand and use the force_code_render parameter automatically. This is especially useful for shell scripts without .sh extensions or other code files with non-standard names.

Configuration:

• To enable/disable automatic code rendering: Set MCP_PRINTER_AUTO_RENDER_CODE to "true" or "false" (default: true)

• To disable automatic code rendering for specific extensions: MCP_PRINTER_CODE_EXCLUDE_EXTENSIONS="json,yaml,html"

• To force code rendering for a specific file: Use the force_code_render parameter in print_file

Color Schemes

The following light themes are recommended for printing (set via MCP_PRINTER_CODE_COLOR_SCHEME):

• atom-one-light (default)

• github

• googlecode

• xcode

• vs

• stackoverflow-light

• gruvbox-light

• solarized-light

Troubleshooting

"Printer not found"

Run lpstat -p in terminal to see exact printer names. They often have underscores instead of spaces.

"Permission denied"

Ensure CUPS is running: sudo cupsctl

"File format not supported"

Some file formats need to be converted to PDF before printing. Export to PDF from the original application or use a conversion tool.

"Chrome not found"

Chrome/Chromium is required for PDF rendering (markdown and code files). It should be auto-detected, but you can specify the path:

Code not rendering with syntax highlighting

1. Ensure Chrome/Chromium is installed (required for PDF generation)

2. Verify MCP_PRINTER_AUTO_RENDER_CODE is set to "true" (it's enabled by default)

3. Check that the file extension is recognized (see Code Rendering)

4. Verify MCP_PRINTER_CODE_EXCLUDE_EXTENSIONS does not include your file's extension

5. Try setting a different color scheme if the current one isn't working

Code prints but with wrong colors/theme

The color scheme might not exist. Try these reliable options:

• atom-one-light (default)

• github

• vs

• xcode

Security

MCP Printer includes multiple security protections to prevent unauthorized file access and system modifications:

File Access Control

The server uses a secure-by-default approach with multiple layers of protection:

Default Allowed Directories

By default, printing is only allowed from these directories:

• ~/Documents

• ~/Downloads

• ~/Desktop

This default configuration covers common use cases while being restrictive. You can configure additional directories as needed.

Universal Dotfile/Dotdir Blocking

All dotfiles and hidden directories are blocked from printing, with no way to override. This prevents access to:

• ~/.ssh (SSH keys)

• ~/.gnupg (GPG keys)

• ~/.aws (AWS credentials)

• ~/.config (application configurations)

• .env files (environment variables)

• Any file or directory starting with . (except . and ..)

This rule applies even if the path is within an allowed directory or specified via symlink. For example:

• ❌ ~/Documents/.secrets.txt (blocked - dotfile)

• ❌ ~/Documents/link → ~/.ssh/id_rsa (blocked - resolves to dotfile)

• ✅ ~/Documents/report.pdf (allowed)

System Directory Protection

Common system directories are always blocked regardless of configuration, including:

• /etc, /var, /root, /sys, /proc, /bin, /boot, /tmp, and more

• /System, /Library, /private/etc, /private/var (macOS)

Custom Security Configuration

You can configure additional allowed paths for specific workflows using environment variables.

Important: When you set MCP_PRINTER_ALLOWED_PATHS, it completely overrides the default allowed directories. You must re-specify them if you want to keep them.

Environment Variable Expansion:

The MCP_PRINTER_ALLOWED_PATHS and MCP_PRINTER_DENIED_PATHS variables support environment variable expansion:

• ~, $HOME, or ${HOME} expand to your home directory

Examples:

Use colon (:) to separate multiple paths, just like the Unix PATH variable.

Additional denied paths can be specified and will be merged with system directory defaults:

Management Operations

Management operations (set_default_printer and cancel_print_job) are disabled by default.

To enable them, set the environment variable:

Note: Only enable management operations if you understand the implications, as they can affect system-wide printer settings and other users' print jobs.

Other Security Features

• Secure temporary files: All temporary files are created in randomly-named directories to prevent race conditions and symlink attacks

• HTML injection protection: File paths are properly escaped when rendered to prevent script injection

• Symlink protection: File paths are resolved to their real paths before validation to prevent bypassing security checks

Development

Setup

Commands

Testing Markdown Rendering

The repository includes reference documents for testing markdown rendering:

Quick test (1 page):

Comprehensive test (2-3 pages):

Use these files to verify markdown rendering quality after making changes to the rendering pipeline.

Running Locally in MCP

Configure your MCP client to run from your local development directory:

Alternative Installation Methods

If you prefer not to use the npx approach in your MCP config, you can install the package globally first:

Then reference it directly in your MCP config (without npx):

Requirements

• macOS or Linux - Uses CUPS printing system

  • macOS: CUPS is built-in

  • Linux: Install CUPS if not present (sudo apt install cups on Ubuntu/Debian)

  • Windows is not currently supported (contributions welcome!)

• Node.js 22+

• Google Chrome or Chromium - Required for both code and markdown PDF rendering (auto-detected)

  • Both Chrome and Chromium work equally well (same browser engine)

  • Auto-detection searches for: Chrome, Chromium, chromium-browser (Linux), Chrome Canary

  • Linux users: chromium or chromium-browser are fully supported

  • You can specify a custom path by setting MCP_PRINTER_CHROME_PATH

• Printers configured in your system

Contributing

Contributions welcome! Areas for improvement:

• Windows support (using Windows Print Spooler)

• More print options

License

MIT