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)

Clone or copy files to CB1:

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

Run the installer:

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

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

Start the service:

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

Manual Installation

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run server
python server.py

VS Code Configuration

Add to your VS Code mcp.json:

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

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

# 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"

# Security
API_KEY = "your-secret-key"
ARMED = False  # Set True to enable dangerous ops
ADMIN_PIN = "1234"

# Camera
CAMERA_SNAPSHOT_URL = "http://localhost/webcam/?action=snapshot"
CAMERA_STREAM_URL = "http://localhost/webcam/?action=stream"

# Spoolman (optional)
SPOOLMAN_ENABLED = False
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 (hours)
MAINTENANCE_INTERVALS = {
    "nozzle": 200,
    "belts": 500,
    "linear_rails": 1000,
    "filters": 100
}

# StealthChanger
TOOL_COUNT = 4

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

klipper-mcp