Fluidd / Klipper 3D Printer MCP Server

An MCP (Model Context Protocol) server that gives AI assistants (Claude, etc.) full real-time control and visibility over 3D printers running Klipper firmware via the Fluidd / Moonraker API stack.

Also includes a standalone local monitor server (monitor_server.py) with a live web UI and multi-channel alerting — push, SMS, email, and iMessage — that fires even when the browser tab is closed.

Features

📊 Real-Time Monitoring

Tool	Description
`get_printer_status`	Full real-time status — state, temps, progress, ETA, position
`get_temperatures`	Hotend, bed, and all extra sensor temperatures
`get_print_job_status`	Current job file, layer, progress, elapsed & ETA
`get_klippy_status`	Klippy firmware health and error messages
`get_moonraker_status`	Moonraker API server health
`get_active_alerts`	All active alerts in one call
`get_printer_logs`	Recent Klippy log lines with error highlighting

🚨 Failure Detection & Alerts

Tool	Description
`check_failure_detection`	Heuristic checks for spaghetti, layer shifts, thermal anomalies, under-extrusion, and stalls
`get_active_alerts`	Continuous alert summary — thermal runaway, Klippy errors, clog detection

Camera integration: Use get_camera_snapshot_url to retrieve live snapshot/stream URLs from Fluidd-configured webcams. For AI-powered visual spaghetti detection, pipe the snapshot URL to a vision model (e.g., Claude's image analysis).

📷 Camera

Tool	Description
`get_camera_snapshot_url`	Snapshot + stream URL(s) for all configured webcams

🖨️ Print Job Management

Tool	Description
`start_print`	Start printing a file from storage
`pause_print`	Pause the current print
`resume_print`	Resume a paused print
`cancel_print`	Cancel the current print
`emergency_stop`	Immediate M112 hardware stop

📋 Queue & File Management

Tool	Description
`get_print_queue`	View the Moonraker job queue
`add_to_queue`	Add a file to the print queue
`remove_from_queue`	Remove a job by ID
`list_print_files`	Browse files on printer storage
`get_print_history`	Recent job history with durations and results

💰 Cost & Profitability

Tool	Description
`calculate_print_cost`	Calculate material + power cost and recommended sale price with configurable markup

⚙️ Printer Control

Tool	Description
`set_temperature`	Set hotend or bed temperature
`send_gcode`	Send any raw G-code command
`restart_klippy`	Restart Klippy service
`restart_firmware`	Firmware restart

Prerequisites

Docker Desktop with MCP Toolkit enabled
A 3D printer running Klipper + Moonraker (exposed on your network)
Fluidd or Mainsail as the front-end (optional — Moonraker API is the interface)
Moonraker API key (if authentication is enabled)
Python 3.7+ (for the monitor server — no extra packages needed)

Quick Start — MCP Server (Claude Desktop)

⚡ Automated Setup (Recommended)

Run the interactive setup script — it handles all steps below, asks for confirmation before making changes, and works on macOS, Linux, and Windows (Git Bash).

git clone https://github.com/block0ps/fluidd-klipper-mcp.git
cd fluidd-klipper-mcp
chmod +x setup.sh
./setup.sh

Or via one-liner (no clone needed):

curl -fsSL https://raw.githubusercontent.com/block0ps/fluidd-klipper-mcp/main/setup.sh | bash

Manual Setup

1. Clone & Build

git clone https://github.com/block0ps/fluidd-klipper-mcp.git
cd fluidd-klipper-mcp
docker build -t fluidd-klipper-mcp-server .

2. Set Secrets

docker mcp secret set PRINTER_HOST="http://192.168.1.100"
docker mcp secret set PRINTER_API_TOKEN="your-moonraker-api-key"

# Cost calculation config (optional — defaults shown)
docker mcp secret set FILAMENT_COST_PER_KG="25.0"
docker mcp secret set POWER_COST_PER_KWH="0.12"
docker mcp secret set PRINTER_WATTS="150.0"
docker mcp secret set MARKUP_PERCENTAGE="30.0"

docker mcp secret list

3. Register in Docker MCP Catalog

mkdir -p ~/.docker/mcp/catalogs
cp custom.yaml ~/.docker/mcp/catalogs/custom.yaml

Add to ~/.docker/mcp/registry.yaml under the registry: key:

registry:
  fluidd-klipper:
    ref: ""

4. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/Users/YOUR_USERNAME/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

5. Restart Claude Desktop

🖥️ Live Monitor & Alerting (`monitor_server.py`)

A standalone Python server that runs locally, serves a live web UI, and dispatches alerts across four channels when anomalies are detected. Polling runs on a background thread — alerts fire even when the browser tab is closed or your screen is locked.

Why a separate server?

Browsers block direct fetch() calls from file:// or https:// pages to local http:// printer IPs (CORS + mixed content policy). monitor_server.py acts as a local proxy: the browser talks to localhost, and Python forwards requests to Moonraker server-side where CORS rules don't apply.

Starting the monitor

# Uses default printer at http://10.0.107.158, port 8484
python3 monitor_server.py

# Custom printer URL
python3 monitor_server.py http://192.168.1.100

# Custom printer URL and port
python3 monitor_server.py http://192.168.1.100 9000

Then open http://localhost:8484 in your browser.

No dependencies beyond Python's standard library — nothing to pip install.

What it monitors

Check	Threshold
🌡️ Thermal anomaly — hotend	Actual vs target divergence > 20°C
🌡️ Thermal anomaly — bed	Actual vs target divergence > 15°C
🔴 Klippy not ready	Any non-`ready` firmware state
🧵 Clog / under-extrusion	< 5mm filament used after 5+ min printing
⏸️ Print stall	No progress after 10+ min printing
📐 Z position anomaly	Z < 0.1mm after 2+ min printing
🛑 Print error / cancelled	State change to `error` or `cancelled`
🎉 Print complete	State change to `complete`

Configuring alert channels

On first run, monitor_server.py creates monitor_config.json in the same directory. Open it, set "enabled": true for each channel you want, fill in the credentials, then restart the server.

{
  "printer_host": "http://10.0.107.158",
  "poll_interval_seconds": 1800,
  "alert_on_warnings": true,

  "ntfy": {
    "enabled": false,
    "topic": "my-printer-alerts",
    "server": "https://ntfy.sh"
  },
  "twilio": {
    "enabled": false,
    "account_sid": "",
    "auth_token": "",
    "from_number": "+1XXXXXXXXXX",
    "to_number": "+1XXXXXXXXXX"
  },
  "email": {
    "enabled": false,
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "username": "you@gmail.com",
    "password": "your-app-password",
    "from_address": "you@gmail.com",
    "to_address": "you@gmail.com"
  },
  "imessage": {
    "enabled": false,
    "to_number": "+1XXXXXXXXXX"
  }
}

📱 Push Notifications — ntfy.sh (free, no account)

ntfy.sh is a free, open-source push notification service.

Install the ntfy app on your phone (iOS / Android)
In the app, tap Subscribe to topic and enter a unique topic name (e.g. mahdi-printer-9482) — treat it like a password, anyone who knows it can send to it
In monitor_config.json:

"ntfy": {
  "enabled": true,
  "topic": "mahdi-printer-9482",
  "server": "https://ntfy.sh"
}

Alerts arrive instantly on your phone with priority levels — critical alerts are marked urgent and bypass Do Not Disturb.

Self-hosting: If you prefer to run your own ntfy server, change "server" to your instance URL.

💬 SMS — Twilio

Sign up at twilio.com (free trial includes test credits)
From the Twilio Console, copy your Account SID and Auth Token
Get a Twilio phone number (free with trial)
In monitor_config.json:

"twilio": {
  "enabled": true,
  "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "auth_token": "your_auth_token",
  "from_number": "+15551234567",
  "to_number": "+15559876543"
}

Trial accounts: Twilio trial numbers can only send to verified phone numbers. Verify your number at Console → Phone Numbers → Verified Caller IDs.

📧 Email — SMTP (Gmail)

In your Google Account, go to Security → 2-Step Verification and enable it
Then go to Security → App Passwords, create a new app password for "Mail"
Copy the 16-character password (spaces don't matter)
In monitor_config.json:

"email": {
  "enabled": true,
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 587,
  "username": "you@gmail.com",
  "password": "abcd efgh ijkl mnop",
  "from_address": "you@gmail.com",
  "to_address": "you@gmail.com"
}

Other providers: Change smtp_host and smtp_port for Outlook (smtp.office365.com, 587), Yahoo (smtp.mail.yahoo.com, 587), or any other SMTP provider.

💬 iMessage — macOS only, no setup required

Uses macOS AppleScript to send iMessages via the Messages app already on your Mac. The Mac running monitor_server.py must be signed into iMessage.

"imessage": {
  "enabled": true,
  "to_number": "+15551234567"
}

to_number accepts a phone number (+15551234567) or an Apple ID email address (you@icloud.com).

Note: macOS may prompt you to grant Terminal (or your Python app) access to Messages the first time. Accept the permission request in System Settings → Privacy & Security → Automation.

Testing alerts

Once configured, use the 🔔 Test Alerts button in the web UI to fire a test message across all enabled channels before walking away from the printer.

You can also trigger an immediate poll (without waiting for the interval) using the 🔄 Poll Now button.

Alert deduplication

Each unique alert fires once per print job — you won't get spammed with repeated SMS messages if a thermal anomaly persists across multiple poll cycles. The dedup set resets automatically when a new print job starts.

Adjusting the poll interval

Change poll_interval_seconds in monitor_config.json and restart the server. Recommended values:

Print type	Suggested interval
Short print (< 2h)	300 (5 min)
Overnight print	900 (15 min)
Multi-day print	1800 (30 min)

🖨️ Multi-Printer Support

Both the MCP server and the monitor support an unlimited number of printers. Each printer is polled on its own background thread; alerts, status, and camera feeds are scoped per printer.

MCP Server — Multiple Printers

Set PRINTER_HOSTS as a JSON array (instead of the single-printer PRINTER_HOST):

[
  {"id": "voron",  "name": "Voron 2.4",  "host": "http://192.168.1.100", "api_token": ""},
  {"id": "ender",  "name": "Ender 5 Pro","host": "http://192.168.1.101", "api_token": ""},
  {"id": "bambu",  "name": "Bambu P1S",  "host": "http://192.168.1.102", "api_token": ""}
]

Via Docker MCP secrets:

docker mcp secret set PRINTER_HOSTS='[{"id":"voron","name":"Voron 2.4","host":"http://192.168.1.100"},{"id":"ender","name":"Ender 5 Pro","host":"http://192.168.1.101"}]'

Once set, Claude can target any printer by name or URL in every tool:

"Check the status of the Voron"
"Pause the Ender"
"What's the bed temp on printer http://192.168.1.102?"
"List all my printers"   ← uses list_printers tool

The list_printers tool shows all configured printers with their IDs and hosts.

Automated setup (adds printers interactively)

./setup.sh
# Step 2 will ask: "Add another printer?" after each one

Monitor Server — Multiple Printers

Initial setup — adding printers during `./setup.sh`

Step 2 of setup.sh loops until you decline to add another printer. Each printer's name, host, and token is collected and written to both PRINTER_HOSTS (Docker MCP) and monitor_config.json.

Adding a printer after initial setup

Option A — interactive CLI (recommended):

python3 monitor_server.py add-printer
# — or via setup.sh shortcut —
./setup.sh add-printer

You'll be prompted for the printer name and host URL. The entry is written to monitor_config.json and a poll thread starts on the next server restart.

Option B — REST API (while server is running):

curl -X POST http://localhost:8484/api/printers \
  -H "Content-Type: application/json" \
  -d '{"name": "Bambu P1S", "host": "http://192.168.1.103", "api_token": ""}'

The printer is registered immediately and starts polling — no restart required.

Option C — edit monitor_config.json directly:

{
  "printers": [
    {"id": "voron",  "name": "Voron 2.4",  "host": "http://192.168.1.100", "enabled": true, "api_token": ""},
    {"id": "ender",  "name": "Ender 5 Pro","host": "http://192.168.1.101", "enabled": true, "api_token": ""}
  ]
}

Then restart monitor_server.py.

Renaming or editing a printer

From the web UI:

Open http://localhost:8484
Click ⚙ Manage next to the printer tabs
Click ✎ Edit on any printer to rename it, change its host URL, or update the API token
Toggle the enable/disable switch to pause monitoring without removing the printer

From the CLI (while server is running):

# Rename
curl -X PATCH http://localhost:8484/api/printers/voron \
  -H "Content-Type: application/json" \
  -d '{"name": "Voron 2.4 — Garage"}'

# Change host
curl -X PATCH http://localhost:8484/api/printers/ender \
  -H "Content-Type: application/json" \
  -d '{"host": "http://10.0.0.55"}'

# Disable monitoring (pauses polling without removing)
curl -X PATCH http://localhost:8484/api/printers/bambu \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Changes are written to monitor_config.json immediately and take effect live.

Direct JSON edit: Modify monitor_config.json and restart the server.

Monitor UI — fleet navigation

Element	Description
Printer tabs	One tab per printer — click to switch the status card
Tab dot colour	🟢 printing, 🟡 paused, 🔴 error, ⚫ idle/standby
⚙ Manage button	Opens the manage panel (edit, rename, enable/disable, add new)
Alert log	Combined across all printers; printer name shown on each entry
Camera button	Fetches snapshot from the currently selected printer's webcam

Alert routing

Alerts from all printers are dispatched over the same channels (ntfy, SMS, email, iMessage). Each notification includes the printer name so you always know which machine fired:

[Voron 2.4] CRITICAL
Thermal anomaly — Bed: target 110°C actual 72.3°C

Once the MCP server is configured, ask Claude:

"What's my printer doing right now?"
"Are there any alerts or errors on the printer?"
"Show me my print queue"
"Start printing benchy.gcode"
"Pause the current print"
"Check for spaghetti or layer shifts"
"What's the camera snapshot URL?"
"How much did this print cost? What should I charge?"
"Set the bed to 60°C"
"Show me the last 20 log lines"
"Restart Klippy"

Cost Calculation

The calculate_print_cost tool uses these configurable parameters:

Env Var	Default	Description
`FILAMENT_COST_PER_KG`	`25.0`	USD per kilogram of filament
`POWER_COST_PER_KWH`	`0.12`	USD per kWh electricity
`PRINTER_WATTS`	`150.0`	Average power draw of your printer
`MARKUP_PERCENTAGE`	`30.0`	Profit margin % on top of costs

Failure Detection

The check_failure_detection and get_active_alerts tools use heuristics against live Moonraker data (same logic as the monitor server):

Detection	Method
Thermal anomaly	Heater actual vs target divergence > 15°C (bed) or 20°C (hotend)
Under-extrusion / clog	Very low filament usage after 5+ min of printing
Layer shift / stall	No Z progress after 10+ min of printing
Z position anomaly	Z < 0.1 mm after 2+ min
Spaghetti (visual)	Pull camera snapshot URL → analyze with vision AI

Architecture

┌─────────────────────────────────────────────────────┐
│                   Your Network                       │
│                                                      │
│  Claude Desktop                                      │
│       │                                              │
│       ▼                                              │
│  MCP Gateway (Docker)                                │
│       │                                              │
│       ▼                                              │
│  fluidd-klipper-mcp-server (Docker)                  │
│       │                          ┌─────────────────┐ │
│       │    monitor_server.py ────┤  Background     │ │
│       │    (localhost:8484)      │  Poll Thread    │ │
│       │         │                └────────┬────────┘ │
│       │         │  Alerts                 │          │
│       │         ├──── 📱 ntfy push        │          │
│       │         ├──── 💬 SMS (Twilio)     │          │
│       │         ├──── 📧 Email (SMTP)     │          │
│       │         └──── 💬 iMessage         │          │
│       │                                  │          │
│       └──────────────────────────────────┘          │
│                        │                             │
│                        ▼ HTTP/REST                   │
│              Moonraker API (printer)                 │
│                        │                             │
│                        ▼                             │
│              Klipper Firmware + Fluidd               │
└─────────────────────────────────────────────────────┘

Development

Local Testing

export PRINTER_HOST="http://192.168.1.100"
export PRINTER_API_TOKEN="your-key"
python3 fluidd_klipper_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python3 fluidd_klipper_server.py

Adding New Tools

Add a new @mcp.tool() function to fluidd_klipper_server.py
Keep the docstring to a single line
Default all parameters to "" (empty string)
Always return a string
Add the tool name to custom.yaml
Rebuild: docker build -t fluidd-klipper-mcp-server .

Security

All secrets stored in Docker Desktop secrets — never hardcoded
Container runs as non-root user (mcpuser)
Sensitive values (API tokens) are never logged
monitor_config.json stores credentials locally — keep it out of version control (it's in .gitignore)
Emergency stop is intentionally available — treat chat access to this server with care

Troubleshooting

Issue	Fix
`Connection refused` on MCP server	Verify `PRINTER_HOST` is reachable from Docker network
`401 Unauthorized` on MCP server	Set `PRINTER_API_TOKEN` via Docker secrets
Tools not appearing in Claude	Rebuild Docker image, restart Claude Desktop
Monitor shows "proxy error"	Ensure `monitor_server.py` is running (`python3 monitor_server.py`)
Push alerts not arriving	Check ntfy topic name matches app subscription; try 🔔 Test Alerts
SMS not sending	Verify Twilio trial number is verified; check account SID / auth token
Email not sending	Use an App Password (not your Gmail login password); ensure 2FA is on
iMessage permission denied	Grant Terminal access in System Settings → Privacy & Security → Automation
Alerts firing repeatedly	Dedup resets per print job — check if a new job started

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
custom.yaml		custom.yaml
fluidd_klipper_server.py		fluidd_klipper_server.py
monitor_server.py		monitor_server.py
printer_monitor.html		printer_monitor.html
requirements.txt		requirements.txt
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation

Fluidd / Klipper 3D Printer MCP Server

Features

📊 Real-Time Monitoring

🚨 Failure Detection & Alerts

📷 Camera

🖨️ Print Job Management

📋 Queue & File Management

💰 Cost & Profitability

⚙️ Printer Control

Prerequisites

Quick Start — MCP Server (Claude Desktop)

⚡ Automated Setup (Recommended)

Manual Setup

1. Clone & Build

2. Set Secrets

3. Register in Docker MCP Catalog

4. Configure Claude Desktop

5. Restart Claude Desktop

🖥️ Live Monitor & Alerting (monitor_server.py)

Why a separate server?

Starting the monitor

What it monitors

Configuring alert channels

📱 Push Notifications — ntfy.sh (free, no account)

💬 SMS — Twilio

📧 Email — SMTP (Gmail)

💬 iMessage — macOS only, no setup required

Testing alerts

Alert deduplication

Adjusting the poll interval

🖨️ Multi-Printer Support

MCP Server — Multiple Printers

Automated setup (adds printers interactively)

Monitor Server — Multiple Printers

Initial setup — adding printers during ./setup.sh

Adding a printer after initial setup

Renaming or editing a printer

Monitor UI — fleet navigation

Alert routing

Cost Calculation

Failure Detection

Architecture

Development

Local Testing

Adding New Tools

Security

Troubleshooting

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

🖥️ Live Monitor & Alerting (`monitor_server.py`)

Initial setup — adding printers during `./setup.sh`

Packages