Which integrations are available for this server?

Enables the server to send 3D print status updates, completion alerts, and temperature notifications to Discord channels via webhooks. Enables the server to send 3D print status updates, completion alerts, and temperature notifications to Slack channels via webhooks.

How do I use Klipper MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Klipper MCP Server check my current print status and nozzle temperature" 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.

Klipper MCP Server

A Model Context Protocol (MCP) server for controlling Klipper 3D printers via Moonraker API. Enables AI assistants like Claude to control your 3D printer through VS Code or any MCP-compatible client.

Overview

This server exposes 100+ tools for complete printer management, from basic operations to advanced diagnostics and toolchanger control. Perfect for Voron, RatRig, or any Klipper-based printer.

Features

🖨️ Core Printer Control

Tool	Description
`get_printer_status`	Full status including temps, position, state
`run_gcode`	Execute any G-code command
`start_print`	Start a print job
`pause_print` / `resume_print`	Print flow control
`cancel_print`	Cancel current print
`home_axes`	Home X/Y/Z or all axes
`emergency_stop`	Immediate halt
`restart_klipper`	Firmware restart
`quad_gantry_level`	Run QGL procedure
`set_heater_temperature`	Set hotend/bed temps

🔧 StealthChanger / Toolchanger Support

Tool	Description
`get_active_tool`	Current tool status
`select_tool`	Pick up tool (T0-T5)
`drop_tool`	Return tool to dock
`initialize_toolchanger`	Run init sequence
`get_tool_offsets`	Tool offset values
`start_tool_alignment`	Alignment workflow
`test_dock_undock`	Test docking operations
`disable_crash_detection`	Disable during testing

⚡ TMC Stepper Driver Control

Tool	Description
`get_tmc_status`	Driver status, currents, temps
`set_tmc_current`	Adjust run/hold current
`dump_tmc_registers`	Register diagnostics
`get_tmc_field` / `set_tmc_field`	Direct register access
`get_autotune_status`	TMC Autotune configuration
`list_tmc_steppers`	All TMC-equipped steppers

💡 LED Effects (klipper-led_effect)

Tool	Description
`list_led_effects`	Available effects
`set_led_effect`	Activate an effect
`stop_led_effect` / `stop_all_effects`	Stop effects
`set_led_color`	Direct RGB/RGBW control
`list_led_scenes`	Preset scenes
`activate_led_scene`	Apply scene preset

📁 File Operations

Tool	Description
`list_gcode_files`	Browse G-code files
`get_file_metadata`	Slicer settings, thumbnails
`read_gcode_file`	Read file contents
`upload_gcode_file`	Upload new files
`delete_gcode_file`	Remove files
`search_in_file`	Search file contents
`list_config_files`	Klipper config files
`read_config_file`	Read printer.cfg etc.

📷 Camera & Timelapse

Tool	Description
`get_camera_snapshot`	Capture current frame
`get_camera_stream_url`	MJPEG stream URL
`get_timelapse_settings`	Current timelapse config
`set_timelapse_enabled`	Enable/disable timelapse
`capture_timelapse_frame`	Manual frame capture
`render_timelapse`	Trigger video render
`configure_timelapse`	Adjust settings

📊 Print Statistics

Tool	Description
`get_print_history`	Past prints with filtering
`get_print_stats`	Cumulative statistics
`get_filament_usage_by_material`	Usage breakdown
`get_recent_prints`	Last N prints summary
`get_average_print_stats`	Average metrics
`export_printer_data`	Export all data to JSON

🔍 Diagnostics & Troubleshooting

Tool	Description
`parse_klippy_log`	Analyze log for issues
`get_recent_errors`	Recent errors with context
`get_log_summary`	Log overview
`check_common_issues`	Config problem detection
`get_mcu_status`	MCU info and timing
`get_gcode_history`	Recent G-code commands
`get_troubleshooting_guide`	Problem-specific help
`analyze_print_failure`	Failure diagnosis
`check_config_issues`	Configuration validation
`get_system_performance`	CPU, memory, disk stats

🌡️ Temperature & Bed Mesh

Tool	Description
`get_temperatures`	All heater temperatures
`get_temperature_history`	Historical temp data
`analyze_temperature_data`	Anomaly detection
`set_temperature_alert`	Threshold alerts
`run_bed_mesh_calibrate`	Run bed mesh
`get_bed_mesh_profiles`	List saved meshes
`load_bed_mesh`	Load a mesh profile
`save_bed_mesh`	Save current mesh
`clear_bed_mesh`	Remove active mesh

🧵 Spoolman Integration

Tool	Description
`list_spools`	All tracked spools
`get_active_spool`	Currently loaded spool
`set_active_spool`	Set spool for tool
`get_spool_details`	Full spool info
`check_low_filament`	Low filament warnings
`get_filament_usage_by_material`	Material statistics
`list_vendors`	Filament vendors
`list_filaments`	Filament database

🔔 Notifications

Tool	Description
`send_notification`	Multi-channel notify
`send_discord_notification`	Discord webhook
`send_slack_notification`	Slack webhook
`send_pushover_notification`	Pushover push
`announce_tts`	Text-to-speech
`test_notifications`	Test all channels
`get_notification_settings`	Current config

💾 Backup & Maintenance

Tool	Description
`backup_config`	Backup all configs
`list_backups`	Available backups
`restore_config`	Restore from backup
`check_maintenance_due`	Maintenance alerts
`log_maintenance`	Record maintenance
`get_maintenance_history`	Maintenance log
`get_audit_log`	Security audit trail
`export_printer_data`	Full data export

📝 G-code Analysis

Tool	Description
`analyze_gcode_file`	Full file analysis
`validate_gcode`	Check for issues
`extract_gcode_comments`	Slicer comments
`get_gcode_moves`	Movement statistics
`extract_layer`	Get specific layer
`compare_gcode_files`	Diff two files

🖥️ System Management

Tool	Description
`get_system_info`	CPU, memory, disk, temp
`get_network_info`	IP addresses, WiFi
`check_updates`	Available updates
`update_component`	Update Klipper/Moonraker
`refresh_update_status`	Check repos
`get_service_status`	Service states
`restart_service`	Restart services
`reboot_system`	System reboot
`shutdown_system`	System shutdown
`get_moonraker_config`	Moonraker info
`get_printer_objects`	Available Klipper objects

Installation

Prerequisites

Klipper + Moonraker running on your printer
Python 3.9+ on your CB1/Raspberry Pi
Network access between VS Code and printer
VS Code with GitHub Copilot (for Claude integration)

Quick Start (5 minutes)

# 1. SSH into your printer ssh biqu@192.168.x.x # or pi@192.168.x.x for Raspberry Pi # 2. Clone the repository cd ~ git clone https://github.com/Charleslotto/klipper-mcp.git cd klipper-mcp # 3. Create config from template cp config.example.py config.py # 4. Generate a secure API key and edit config python3 -c "import secrets; print(secrets.token_urlsafe(32))" nano config.py # Paste the API key and adjust settings # 5. Run the installer chmod +x install.sh ./install.sh # 6. Start the service sudo systemctl start klipper-mcp sudo systemctl enable klipper-mcp # Auto-start on boot

Verify Installation

# Check service is running sudo systemctl status klipper-mcp # Test the API (replace with your API key) curl -H "X-API-Key: your-api-key" http://localhost:8000/health # View logs journalctl -u klipper-mcp -f

Configuration

Copy config.example.py to config.py and customize:

nano ~/klipper-mcp/config.py

Required settings:

Setting	Description	Example
`API_KEY`	Secure authentication key	`python3 -c "import secrets; print(secrets.token_urlsafe(32))"`
`MOONRAKER_URL`	Your Moonraker address	`http://localhost:7125`
`PRINTER_NAME`	Display name	`Voron 2.4`

Security settings:

Setting	Description	Default
`ARMED`	Enable dangerous operations	`false`
`ADMIN_PIN`	PIN for destructive ops	`123456`

Optional integrations:

Setting	Description
`SPOOLMAN_ENABLED`	Enable Spoolman filament tracking
`TOOL_COUNT`	Number of toolchanger tools
`DISCORD_WEBHOOK_URL`	Discord notifications

Setting Up VS Code MCP Client

Method 1: User Settings (Recommended)

Add to your VS Code settings.json (Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"):

{ "mcp": { "servers": { "voron": { "type": "http", "url": "http://192.168.x.x:8000/mcp", "headers": { "X-API-Key": "your-api-key-here" } } } } }

Method 2: Workspace Config

Create .vscode/mcp.json in your project:

{ "mcpServers": { "voron": { "type": "http", "url": "http://192.168.x.x:8000/mcp", "headers": { "X-API-Key": "your-api-key-here" } } } }

Method 3: Multiple Printers

Configure multiple printers in settings.json:

{ "mcp": { "servers": { "voron-2.4": { "type": "http", "url": "http://192.168.1.100:8000/mcp", "headers": { "X-API-Key": "key-for-voron" } }, "voron-0.2": { "type": "http", "url": "http://192.168.1.101:8000/mcp", "headers": { "X-API-Key": "key-for-v0" } } } } }

Verify Connection

Open VS Code with Copilot
Open the Copilot Chat panel
Type: @voron what's your status?
Claude should respond with your printer's status

Troubleshooting:

Ensure the CB1/Pi IP address is reachable: ping 192.168.x.x
Check firewall allows port 8000: sudo ufw allow 8000
Verify API key matches exactly in VS Code and config.py
Check service is running: sudo systemctl status klipper-mcp

Security

ARMED Flag

Dangerous operations (G-code execution, temperature changes) require ARMED=True in config.

Admin PIN

Destructive operations (file deletion, config restore, system reboot) require the admin PIN.

API Key

All requests must include a valid X-API-Key header matching your config.

Audit Log

All operations are logged to data/audit.log for security review.

Configuration Reference

# config.py # Moonraker connection MOONRAKER_URL = "http://localhost:7125" PRINTER_NAME = "Voron" # MCP Server MCP_HOST = "0.0.0.0" MCP_PORT = 8000 MCP_TRANSPORT = "http" # or "stdio" for local use # Security API_KEY = "your-secret-key" # Required for all API calls ARMED = False # Set True to enable dangerous ops ADMIN_PIN = "1234" # For destructive operations # Camera CAMERA_SNAPSHOT_URL = "http://localhost/webcam/?action=snapshot" CAMERA_STREAM_URL = "http://localhost/webcam/?action=stream" # Spoolman (optional) SPOOLMAN_ENABLED = True SPOOLMAN_URL = "http://localhost:7912" # Notifications (optional) DISCORD_WEBHOOK_URL = "" SLACK_WEBHOOK_URL = "" PUSHOVER_USER_KEY = "" PUSHOVER_API_TOKEN = "" # Text-to-Speech (optional) TTS_ENABLED = False TTS_RATE = 150 TTS_VOLUME = 1.0 # Maintenance intervals (print hours) MAINTENANCE_INTERVALS = { "nozzle": 200, "belts": 500, "linear_rails": 1000, "filters": 100 } # StealthChanger / Toolchanger TOOL_COUNT = 4 # Number of tools (T0-T3)

Usage Examples

Basic Commands

"What's my printer's current status?" "Set the bed to 60°C and hotend to 210°C" "Start printing benchy.gcode" "Pick up T1" / "Drop the current tool"

🧵 Bulk Import Filament Database into Spoolman

User: "I want to bulk import filaments into Spoolman from the community database"

Claude: I'll fetch the external filament database and import everything for you...

Result:

Fetched 6,957 filaments from SpoolmanDB community database
Created 53 vendors (Polymaker, eSun, Bambu Lab, Prusament, Hatchbox, etc.)
Imported 5,223 filaments with full specifications:
- Material types: PLA (2,466), PETG (943), ASA (526), ABS (467), TPU (312)...
- Includes density, diameters, temp ranges, colors
All searchable in Spoolman UI

🔍 System Health Check After Heavy Operation

User: "How is the Voron's load now that Spoolman has all that data?"

Claude: Let me check the system status...

┌──────────────────────────────────────┐ │ System Load After Spoolman Import │ ├─────────────┬────────────┬───────────┤ │ CPU Load │ 1.32 │ 🟢 Normal │ │ Memory │ 60% used │ 🟢 OK │ │ Disk │ 38% used │ 🟢 OK │ │ CPU Temp │ 45.7°C │ 🟢 Cool │ │ CAN Bus │ All Active │ 🟢 OK │ └─────────────┴────────────┴───────────┘

Analysis: Spoolman runs on a separate machine, so the 5,223 filaments don't impact Klipper. Load settled from 1.71 → 1.32 after initial indexing.

🛠️ Configuration Audit & Diagnostics

User: "Can you audit my Voron's configuration?"

Claude: I'll analyze your printer configuration and logs...

Results:

Configuration Issues Found: ⚠️ Klipper git state: dirty/invalid - uncommitted changes ⚠️ TMC Autotune: Installed but not configured for all steppers ⚠️ Hold current: Using default 50% - consider optimizing Recommendations: 1. Run 'git stash' in Klipper directory to clean state 2. Add [autotune_tmc] sections for stepper_x, stepper_y, stepper_z 3. Set hold_current to 40% for lower idle power consumption No Critical Errors Found ✅ CAN Bus: All 4 MCUs communicating properly TMC Drivers: No errors, all steppers responding

🌡️ Temperature Anomaly Detection

User: "Analyze my temperature data for any issues"

Claude: Analyzing temperature history...

Temperature Analysis (Last 24 Hours) ──────────────────────────────────── Hotend (extruder): ✅ Stable PID tuning - variance: ±0.3°C ✅ No thermal runaway events Bed (heater_bed): ⚠️ Detected 2 oscillations during warmup 💡 Consider re-running PID_CALIBRATE BED Chamber: ✅ Consistent 45°C during ABS prints MCU Temperatures: ✅ All MCUs under 50°C

🔧 TMC Driver Optimization

User: "What are my TMC driver settings and can they be improved?"

Claude: Let me check your TMC configuration...

TMC Driver Status ───────────────────────────────────────────────── Stepper │ Driver │ Run │ Hold │ Temp ─────────────┼──────────┼────────┼────────┼────── stepper_x │ TMC2209 │ 0.800A │ 0.400A │ 42°C stepper_y │ TMC2209 │ 0.800A │ 0.400A │ 44°C stepper_z │ TMC2209 │ 0.800A │ 0.600A │ 38°C stepper_z1 │ TMC2209 │ 0.800A │ 0.600A │ 39°C stepper_z2 │ TMC2209 │ 0.800A │ 0.600A │ 37°C stepper_z3 │ TMC2209 │ 0.800A │ 0.600A │ 38°C extruder │ TMC2209 │ 0.650A │ 0.325A │ 41°C TMC Autotune: ⚠️ Installed but needs motor configuration Recommendation: Add motor specs to enable automatic tuning

📊 Print Statistics & Filament Usage

User: "Show me my print statistics and filament usage"

Claude: Here's your printing summary...

Lifetime Statistics ─────────────────── Total Prints: 847 Success Rate: 94.2% Total Print Time: 1,247 hours Total Filament: 12.4 kg Filament by Material ──────────────────── PLA │ ████████████████████ │ 6.2 kg (50%) PETG │ ████████████ │ 3.1 kg (25%) ABS │ ████████ │ 2.0 kg (16%) ASA │ ████ │ 1.1 kg (9%) Recent Prints (Last 7 Days) ─────────────────────────── ✅ voron_panel_x4.gcode │ 4h 23m │ PETG ✅ cable_chain.gcode │ 2h 15m │ ABS ✅ benchy.gcode │ 0h 42m │ PLA ❌ large_vase.gcode │ Failed │ Layer shift @ 45%

🔄 Multi-Tool Print Setup

User: "I want to print a dual-color model, help me set up the tools"

Claude: Let me configure your toolchanger...

Current Tool Status ─────────────────── T0 (extruder): 🔵 Active - Docked T1 (extruder1): ⚪ Ready - Docked T2 (extruder2): ⚪ Ready - Docked Setting up for dual-color print: 1. ✅ Set T0 active spool: Polymaker PLA Pro - Blue (ID: 142) 2. ✅ Set T1 active spool: Polymaker PLA Pro - White (ID: 156) 3. ✅ Verified tool offsets are calibrated 4. ✅ Both hotends at target temp (210°C) Ready to print! The slicer should handle tool changes automatically.

💾 Automated Backup Before Update

User: "I want to update Klipper but backup my config first"

Claude: I'll create a backup and then check for updates...

Backup Created ────────────── 📁 backup_2026-01-26_143022.tar.gz - printer.cfg - moonraker.conf - mainsail.cfg - 12 include files Total: 847 KB Available Updates ───────────────── Component │ Current │ Available │ Status ─────────────┼─────────────┼─────────────┼──────── Klipper │ v0.12.0-145 │ v0.12.0-152 │ 7 commits behind Moonraker │ v0.8.0-401 │ v0.8.0-401 │ ✅ Up to date Mainsail │ v2.9.1 │ v2.10.0 │ Update available Would you like me to proceed with updating Klipper?

Optional Integrations

Spoolman

Enable filament tracking by setting up Spoolman:

cd ~/klipper-mcp/scripts chmod +x install_spoolman.sh ./install_spoolman.sh

Then update config.py:

SPOOLMAN_ENABLED = True SPOOLMAN_URL = "http://localhost:7912"

TMC Autotune

For automatic TMC tuning, install klipper_tmc_autotune.

LED Effects

For animated LEDs, install klipper-led_effect.

Troubleshooting

Server won't start

# Check Moonraker is running systemctl status moonraker # Check logs journalctl -u klipper-mcp -f # Verify config python3 -c "import config; print(config.MOONRAKER_URL)"

Can't connect from VS Code

Verify CB1/Pi IP address is correct
Check firewall allows port 8000: sudo ufw allow 8000
Verify API key matches in VS Code and config.py
Test: curl -H "X-API-Key: your-key" http://ip:8000/health

Operations failing

Check ARMED=True for dangerous operations
Verify Klipper is running and ready: systemctl status klipper
Check klippy.log: tail -f ~/printer_data/logs/klippy.log

Spoolman not working

Verify Spoolman is running: systemctl status spoolman
Check URL in config.py matches Spoolman's address
Test: curl http://localhost:7912/api/v1/health

Project Structure

klipper-mcp/ ├── server.py # Main MCP server ├── moonraker.py # Moonraker API client ├── config.py # Configuration ├── requirements.txt # Python dependencies ├── install.sh # Installation script ├── klipper-mcp.service # Systemd service file ├── tools/ # MCP tool implementations │ ├── printer.py # Core printer control │ ├── toolchanger.py # Toolchanger/StealthChanger │ ├── tmc.py # TMC driver control │ ├── led_effects.py # LED animations │ ├── filesystem.py # File operations │ ├── camera.py # Camera & timelapse │ ├── statistics.py # Print history │ ├── diagnostics.py # Error analysis │ ├── temperature.py # Temp control & mesh │ ├── spoolman.py # Filament tracking │ ├── notifications.py# Alerts & TTS │ ├── backup.py # Backup & maintenance │ ├── gcode_analysis.py # G-code parsing │ └── system.py # System management ├── data/ # Runtime data │ ├── audit.log # Security log │ └── maintenance.json# Maintenance records ├── backups/ # Config backups ├── scenes/ # LED scene presets │ └── led_scenes.json └── docs/ # Documentation

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Add tests if applicable
Submit a pull request

License

MIT License - See LICENSE file for details.

Acknowledgments

Klipper - 3D printer firmware
Moonraker - Klipper API server
Model Context Protocol - AI tool protocol
StealthChanger - Toolchanger system
Spoolman - Filament management