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.

Features

Core Printer Control

• Get printer status, temperatures, and position

• Run G-code commands

• Start, pause, resume, and cancel prints

• Home axes and emergency stop

• Klipper firmware restart

StealthChanger Toolchanger

• Select tools (T0-T5)

• Initialize toolchanger

• Tool alignment workflow

• Crash detection control

• Tool dock/pickup operations

LED Effects (klipper-led_effect)

• Set LED effects and animations

• Stop effects (single or all)

• LED scene presets (idle, printing, complete, etc.)

• Direct LED color control

File Operations

• List and read G-code files

• Upload and delete files

• Search within files

• Get G-code metadata

Camera & Timelapse

• Capture webcam snapshots

• Get stream URLs

• Timelapse settings and control

• Manual frame capture

Print Statistics

• Print history with filtering

• Cumulative totals (time, filament)

• Filament usage analysis

• Recent prints summary

Diagnostics

• Parse klippy.log for errors

• Common issue detection

• MCU status

• G-code history

• Problem troubleshooting guide

Temperature & Bed Mesh

• Temperature history

• Anomaly detection

• Bed mesh profiles

• Mesh calibration

Spoolman Integration

• List and track filament spools

• Set active spool

• Low filament warnings

• Usage by material

Notifications

• Discord, Slack, Pushover webhooks

• Text-to-speech announcements

• Print completion alerts

• Temperature alerts

Backup & Maintenance

• Config file backup/restore

• Maintenance logging

• Due maintenance alerts

• Data export

G-code Analysis

• File analysis and metadata

• Comment extraction

• Move statistics

• Layer extraction

• Validation checks

Installation

On CB1 (BigTreeTech)

1. Clone or copy files to CB1:

   cd ~ git clone <repo-url> klipper-mcp # Or copy files via SCP/SFTP

2. Run the installer:

   cd ~/klipper-mcp chmod +x install.sh ./install.sh

3. Configure settings:

   nano ~/klipper-mcp/config.py

   Update these settings:

   • MOONRAKER_URL: Usually http://localhost:7125

   • PRINTER_NAME: Your printer name

   • API_KEY: Generate a secure key

   • ADMIN_PIN: Set a PIN for destructive operations

   • ARMED: Set to True when ready

4. Start the service:

   sudo systemctl start klipper-mcp sudo systemctl status klipper-mcp

Manual Installation

VS Code Configuration

Add to your VS Code mcp.json:

Replace 192.168.2.87 with your CB1's IP address.

Security

ARMED Flag

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

Admin PIN

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

Audit Log

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

Configuration Reference

Troubleshooting

Server won't start

• Check Moonraker is running: systemctl status moonraker

• Verify config.py settings

• Check logs: tail -f /var/log/klipper-mcp.log

Can't connect from VS Code

• Verify CB1 IP address

• Check firewall allows port 8000

• Verify API key matches

Operations failing

• Check ARMED=True for dangerous operations

• Verify Klipper is running and ready

• Check klippy.log for errors

License

MIT License