ipp-bridge-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ipp-bridge-mcp Validate and print the PDF I just uploaded, file ID a7f9c1."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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) viaAuthorization: BearerorX-API-Key.
Dual Print Backends (
auto|ipp|lp):Direct IPP/IPPS (
httpx+ RFC 8010/8011 codec): Handlesipp://,ipps://,http://, andhttps://printer URIs, normalizes root URLs to/ipp/print, supports--insecureself-signed certs and automatic TLS 1.2 (@SECLEVEL=1) compatibility for enterprise/embedded printer firmware (verified against HP LaserJet M806).CUPS
lpCLI: Argument-safeasyncio.create_subprocess_execwrappers forlp,lpstat,lpoptions, andcancel.
Flexible Deployment Topologies:
Embedded stdio mode (
--with-upload-api): FastMCP overstdio+ background FastAPI Upload API in oneuvxcommand.Combined HTTP mode (
--transport streamable-http): Serves both FastAPI upload routes (/upload,/files,/print,/health) and FastMCP (/mcp) on a single port.Split-host mode: Run
ipp-bridge-apion your CUPS host and pointipp-bridge-mcp --upload-api-url http://cups-host:8000at 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 8000Upload a file via HTTP:
curl -F "file=@document.pdf" http://127.0.0.1:8000/uploadResponse:
{
"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 \
--insecureUpload API:
http://127.0.0.1:8000/upload,/files,/health,/docsFastMCP 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_LaserJetOn 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_LaserJetMCP 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 config, staging dir, and backend availability |
| Stage text or base64 content through the upload bridge |
| List non-expired staged files |
| Fetch metadata and |
| Delete a staged file |
| Discover configured IPP and/or CUPS printers |
| Query supported formats, media, state, and toner markers |
| Preflight validate via IPP |
| Print staged |
| List active or completed jobs |
| Query status for a specific |
| Cancel a queued or active job |
| Trigger IPP |
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 countPOST /upload— Multipart file upload (file), returnsfile_id&local_pathGET /files— List staged uploadsGET /files/{file_id}— Get staged file metadataGET /files/{file_id}/content— Download staged file bytesDELETE /files/{file_id}— Remove staged filePOST /print— Print a stagedfile_idorlocal_pathdirectly via IPP orlpGET /printers,GET /jobs,GET /jobs/{job_id},POST /jobs/{job_id}/cancel
Configuration Environment Variables
Variable | Description | Default |
| Target IPP/IPPS/HTTP(S) printer URI |
|
| Default CUPS destination for |
|
|
|
|
| Disable TLS certificate verification ( |
|
| Staging directory |
|
| Remote Upload API URL |
|
| Optional auth key for Upload API |
|
| Max upload size in bytes |
|
| Staging TTL in seconds |
|
| Allow printing paths outside |
|
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 liveLicense
MIT
Available Tools
13 toolsbridge_statusBridge StatusARead-only
Return bridge configuration, staging directory, and active backend availability.
Inputs: no named parameters. Returns: object
cancel_jobCancel JobBDestructive
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 FileBDestructive
Delete a staged uploaded file from temporary storage by file_id.
Inputs: file_id (required). Returns: object
get_job_statusGet Job StatusCRead-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 AttributesCRead-only
Query detailed printer status, supported formats, media, and marker levels.
Inputs: backend, printer_uri, printer_name. Returns: object
get_uploaded_fileGet Uploaded FileARead-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 JobsBRead-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 PrintersBRead-only
List configured IPP printers and/or local CUPS destinations.
Inputs: backend. Returns: result
list_uploaded_filesList Uploaded FilesARead-only
List non-expired files currently staged in the temporary upload store.
Inputs: no named parameters. Returns: result
print_filePrint FileC
Print a staged file (by file_id or local_path) directly via IPP or CUPS lp.
Inputs: media, sides, copies, backend, +17 more. Returns: object
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 JobBRead-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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
HTML/URL to PDF rendering API with a remote MCP server. Send HTML or a URL, get a print-ready PDF back.
MCP server for the PDFGate API. Generate PDFs, manage documents and handle e-signatures.
Screenshots, PDFs, image editing, QR codes, email validation and more through one hosted MCP server.
HTML and CSS to PDF MCP server with page headers, footers and page numbers. No headless browser.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA cross-platform MCP server that enables AI assistants to manage printers, query printer status, and print files on Windows, macOS, and Linux.14-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to submit, slice, and start 3D prints with configurable gates, preview approval, and monitoring, via a self-hosted print daemon.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to submit PDFs or JSON-rendered templates to local printers, check printer status, and manage print jobs through MCP tools.9 npmMIT
- AlicenseAqualityBmaintenanceEnables 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.7MIT