Skip to main content
Glama
ipp-bridge-mcp

ipp-bridge-mcp

ipp-bridge-mcp

A lightweight HTTP Upload + IPP / CUPS Bridge built with FastAPI and FastMCP.

External clients or web workflows upload documents via POST /upload (multipart/form-data), which saves them securely to a temporary staging directory and returns a file_id and local_path. The FastMCP server then passes the staged file directly to an IPP/IPPS printer (RFC 8010/8011 binary protocol) or the CUPS lp command.

┌────────────┐  POST /upload (multipart)   ┌──────────────────────┐
│ HTTP / AI  ├────────────────────────────►│ FastAPI Upload API   │
│  Client    │◄────────────────────────────┤ (temp staging store) │
└─────┬──────┘  {file_id, local_path}      └──────────┬───────────┘
      │                                               │
      │ MCP tool: print_file(file_id / local_path)    │ resolves file_id / local_path
      ▼                                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    FastMCP Server (ipp-bridge-mcp)              │
├──────────────────────────────┬──────────────────────────────────┤
│ Direct IPP/IPPS Backend      │ CUPS CLI Backend                 │
│ (Print-Job / Validate-Job /  │ (lp / lpstat / lpoptions /       │
│  Get-Printer-Attributes)     │  cancel)                         │
└──────────────┬───────────────┴──────────────────┬───────────────┘
               ▼                                  ▼
     ipps://localhost:6250/ipp/print         CUPS daemon (lp)

Features

  • Lightweight Multipart Upload API (FastAPI):

    • Streaming uploads with SHA-256 checksums, filename sanitization, path-traversal protection, magic-byte MIME detection (application/pdf, application/postscript, image/png, image/jpeg, image/tiff, text/plain, etc.), configurable max byte size, and automatic TTL expiration cleanup.

    • Optional API key protection (--api-key / IPP_BRIDGE_API_KEY) via Authorization: Bearer or X-API-Key.

  • Dual Print Backends (auto | ipp | lp):

    • Direct IPP/IPPS (httpx + RFC 8010/8011 codec): Handles ipp://, ipps://, http://, and https:// printer URIs, normalizes root URLs to /ipp/print, supports --insecure self-signed certs and automatic TLS 1.2 (@SECLEVEL=1) compatibility for enterprise/embedded printer firmware (verified against HP LaserJet M806).

    • CUPS lp CLI: Argument-safe asyncio.create_subprocess_exec wrappers for lp, lpstat, lpoptions, and cancel.

  • Flexible Deployment Topologies:

    1. Embedded stdio mode (--with-upload-api): FastMCP over stdio + background FastAPI Upload API in one uvx command.

    2. Combined HTTP mode (--transport streamable-http): Serves both FastAPI upload routes (/upload, /files, /print, /health) and FastMCP (/mcp) on a single port.

    3. Split-host mode: Run ipp-bridge-api on your CUPS host and point ipp-bridge-mcp --upload-api-url http://cups-host:8000 at it.


Related MCP server: printd

Quick Start with uvx

1. Run MCP (stdio) + Upload API against a forwarded IPPS printer

uvx --from git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git \
  ipp-bridge-mcp \
  --printer-uri https://localhost:6250 \
  --insecure \
  --with-upload-api \
  --upload-port 8000

Upload a file via HTTP:

curl -F "file=@document.pdf" http://127.0.0.1:8000/upload

Response:

{
  "file_id": "a7f9c1...",
  "filename": "document.pdf",
  "local_path": "/tmp/ipp-bridge-uploads/a7f9c1.../document.pdf",
  "content_type": "application/pdf",
  "size_bytes": 48210,
  "sha256": "...",
  "created_at": "2026-11-16T08:00:00Z",
  "expires_at": "2026-11-16T09:00:00Z"
}

Then ask your MCP client to validate and print file_id (or local_path) via validate_print_job and print_file.

2. Run Combined Streamable HTTP + Upload API on one port

uvx --from git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git \
  ipp-bridge-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --printer-uri https://localhost:6250 \
  --insecure
  • Upload API: http://127.0.0.1:8000/upload, /files, /health, /docs

  • FastMCP endpoint: http://127.0.0.1:8000/mcp

3. Split-Host Mode (CUPS Host Upload API + Remote FastMCP)

On the CUPS host:

uvx --from git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git \
  ipp-bridge-api \
  --host 0.0.0.0 \
  --port 8000 \
  --backend lp \
  --cups-printer Office_LaserJet

On the MCP client host:

uvx --from git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git \
  ipp-bridge-mcp \
  --upload-api-url http://cups-host:8000 \
  --backend lp \
  --cups-printer Office_LaserJet

MCP Client Configuration (mcp_config.json)

{
  "mcpServers": {
    "ipp-bridge": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hkbu-kennycheng/ipp-bridge-mcp.git",
        "ipp-bridge-mcp",
        "--printer-uri",
        "https://localhost:6250",
        "--insecure",
        "--with-upload-api",
        "--upload-port",
        "8000"
      ]
    }
  }
}

FastMCP Tools, Resources, and Prompts

Tool

Description

bridge_status

Bridge config, staging dir, and backend availability

upload_file

Stage text or base64 content through the upload bridge

list_uploaded_files

List non-expired staged files

get_uploaded_file

Fetch metadata and local_path by file_id

delete_uploaded_file

Delete a staged file

list_printers

Discover configured IPP and/or CUPS printers

get_printer_attributes

Query supported formats, media, state, and toner markers

validate_print_job

Preflight validate via IPP Validate-Job or CUPS check (no paper printed)

print_file

Print staged file_id or local_path via IPP Print-Job or CUPS lp

list_jobs

List active or completed jobs

get_job_status

Query status for a specific job_id

cancel_job

Cancel a queued or active job

identify_printer

Trigger IPP Identify-Printer (display, flash, sound)

Resources: ipp-bridge://status, ipp-bridge://files, ipp-bridge://printer/attributes
Prompt: print_uploaded_document

HTTP Upload + Bridge API Endpoints

  • GET /health — Service health & staged file count

  • POST /upload — Multipart file upload (file), returns file_id & local_path

  • GET /files — List staged uploads

  • GET /files/{file_id} — Get staged file metadata

  • GET /files/{file_id}/content — Download staged file bytes

  • DELETE /files/{file_id} — Remove staged file

  • POST /print — Print a staged file_id or local_path directly via IPP or lp

  • GET /printers, GET /jobs, GET /jobs/{job_id}, POST /jobs/{job_id}/cancel

Configuration Environment Variables

Variable

Description

Default

IPP_BRIDGE_PRINTER_URI

Target IPP/IPPS/HTTP(S) printer URI

None

IPP_BRIDGE_CUPS_PRINTER

Default CUPS destination for lp

None

IPP_BRIDGE_BACKEND

auto, ipp, or lp

auto

IPP_BRIDGE_INSECURE

Disable TLS certificate verification (1/true)

false

IPP_BRIDGE_UPLOAD_DIR

Staging directory

<temp>/ipp-bridge-uploads

IPP_BRIDGE_UPLOAD_API_URL

Remote Upload API URL

None

IPP_BRIDGE_API_KEY

Optional auth key for Upload API

None

IPP_BRIDGE_MAX_UPLOAD_BYTES

Max upload size in bytes

52428800 (50 MiB)

IPP_BRIDGE_FILE_TTL

Staging TTL in seconds

3600

IPP_BRIDGE_ALLOW_LOCAL_PATHS

Allow printing paths outside upload_dir

false


Development & Testing

uv sync --extra dev
uv run ruff check src tests
uv run mypy src
uv run pytest -v -m "not live"

Run live printer E2E tests (uses Get-Printer-Attributes, Validate-Job, Create-Job, Get-Job-Attributes, and Cancel-Job — zero paper consumed):

IPP_BRIDGE_LIVE_PRINTER_URI=https://localhost:6250 uv run pytest -v -m live

License

MIT

Available Tools

13 tools
bridge_statusBridge StatusA
Read-only

Return bridge configuration, staging directory, and active backend availability.

Inputs: no named parameters. Returns: object

cancel_jobCancel JobB
Destructive

Cancel a queued or active print job by job_id.

Inputs: job_id (required), backend, printer_uri, printer_name. Returns: object

delete_uploaded_fileDelete Uploaded FileB
Destructive

Delete a staged uploaded file from temporary storage by file_id.

Inputs: file_id (required). Returns: object

get_job_statusGet Job StatusC
Read-only

Get attributes and state for a specific print job ID.

Inputs: job_id (required), backend, printer_uri, printer_name. Returns: object

get_printer_attributesGet Printer AttributesC
Read-only

Query detailed printer status, supported formats, media, and marker levels.

Inputs: backend, printer_uri, printer_name. Returns: object

get_uploaded_fileGet Uploaded FileA
Read-only

Retrieve metadata and local_path for a staged uploaded file by file_id.

Inputs: file_id (required). Returns: object

identify_printerIdentify PrinterC

Trigger IPP Identify-Printer (e.g. display message on printer panel or flash).

Inputs: actions, message, printer_uri. Returns: object

list_jobsList JobsB
Read-only

List active or completed print jobs on the IPP printer or CUPS queue.

Inputs: limit, backend, which_jobs, printer_uri, +1 more. Returns: result

list_printersList PrintersB
Read-only

List configured IPP printers and/or local CUPS destinations.

Inputs: backend. Returns: result

list_uploaded_filesList Uploaded FilesA
Read-only

List non-expired files currently staged in the temporary upload store.

Inputs: no named parameters. Returns: result

upload_fileUpload FileA

Stage a text or base64-encoded binary file through the upload bridge.

Returns file_id and local_path that can be passed to validate_print_job or print_file.

Inputs: filename (required), ttl_seconds, content_text, content_type, +1 more. Returns: object

validate_print_jobValidate Print JobB
Read-only

Validate an uploaded file_id or local_path against the printer without printing.

Inputs: media, sides, copies, backend, +14 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 13 tools

    Disambiguation4/5

    Each tool maps to a distinct resource+action across three clear groups (uploaded files, print jobs, printers), and descriptions make boundaries readable. Minor overlap exists between bridge_status and get_printer_attributes (both report 'status' at different layers), which could cause an occasional misselection.

    Naming Consistency4/5

    Strong snake_case verb_noun convention throughout (upload_file, list_jobs, get_job_status, cancel_job, delete_uploaded_file). The lone deviation is bridge_status, which puts the noun first instead of following the get_/list_ verb pattern.

    Tool Count5/5

    13 tools is well within the ideal range for a print-bridge server, with sensible coverage of uploads, jobs, and printer discovery. Each tool appears to earn its place; nothing looks redundant or padded.

    Completeness4/5

    Full lifecycle is covered for staged uploads (upload, list, get, delete) and jobs (list, status, cancel, submit via print_file), plus printer discovery and validation. Gaps remain around job control (hold/release/pause/resume) and any cleanup of expired jobs, but core workflows have no dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A cross-platform MCP server that enables AI assistants to manage printers, query printer status, and print files on Windows, macOS, and Linux.
      14
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to submit, slice, and start 3D prints with configurable gates, preview approval, and monitoring, via a self-hosted print daemon.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to submit PDFs or JSON-rendered templates to local printers, check printer status, and manage print jobs through MCP tools.
      9 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables printing labels whose layout adapts to the roll reported by a CUPS/IPP label printer, as well as PDF, Markdown, and HTML documents, with preview, copies, duplex, page ranges, and print-job management.
      7
      MIT