Klipper MCP Server

Klipper MCP服务器

一种模型上下文协议（MCP）服务器，用于通过Moonraker API控制Klipper 3D打印机。使Claude等AI助手能够通过VS Code或任何兼容MCP的客户端控制您的3D打印机。

概述

此服务器公开 100+工具 用于从基本操作到高级诊断和换刀器控制的完整打印机管理。非常适合Voron、RatRig或任何基于Klipper的打印机。

特性

🖨️ 核心打印机控制

🔧 隐形换刀/换刀支架

⚡ TMC步进驱动器控制

💡 LED效果（klipper-LED_effect）

📁 文件操作

📷 相机和延时摄影

📊 打印统计信息

🔍 诊断和故障排除

🌡️ 温度和床网

🧵 斯波尔曼融合

🔔 通知

💾 备份和维护

📝 G-代码分析

🖥️ 系统管理

安装

先决条件

• Klipper+Moonraker在您的打印机上运行
• CB1/Raspberry Pi上的Python 3.9+
• VS Code与打印机之间的网络连接
• VS代码与GitHub Copilot（用于Claude集成）

快速入门（5分钟）

# 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

验证安装

# 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

配置

复制 config.example.py 到 config.py 并自定义：

nano ~/klipper-mcp/config.py

所需设置：

安全设置：

可选集成：

______________________________________________________________________

设置VS代码MCP客户端

方法1：用户设置（推荐）

添加到您的VS代码 settings.json (Ctrl+Shift+P → “首选项：打开用户设置（JSON）”）：

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

方法2：工作区配置

创建 .vscode/mcp.json 在您的项目中：

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

方法3：多台打印机

在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" }
      }
    }
  }
}

验证连接

1. 使用Copilot打开VS代码
2. 打开副驾驶聊天面板
3. 类型： @voron what's your status?
4. Claude应回复您的打印机状态

故障排除：

• 确保CB1/Pi IP地址可访问： ping 192.168.x.x
• 检查防火墙是否允许端口8000： sudo ufw allow 8000
• 在VS Code和config.py中验证API键是否完全匹配
• 检查服务是否正在运行： sudo systemctl status klipper-mcp

______________________________________________________________________

安全

武装旗帜

危险操作（G代码执行、温度变化）需要 ARMED=True 在配置中。

管理员PIN

破坏性操作（文件删除、配置还原、系统重新启动）需要管理员PIN。

API密钥

所有请求都必须包含有效的 X-API-Key 标题与您的配置相匹配。

审核日志

所有操作都记录到 data/audit.log 用于安全审查。

配置参考

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

用法示例

基本命令

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

______________________________________________________________________

🧵 将长丝数据库批量导入Spoolman

用户： “我想从社区数据库批量导入细丝到斯波尔曼”

克劳德： 我会获取外部灯丝数据库，并为您导入所有内容。..

结果：

• 从SpoolmanDB社区数据库中获取了6957根细丝
• 创建了53家供应商（Polymaker、eSun、Bambu Lab、Prusament、Hatchbox等）
• 进口5223根长丝，规格齐全：

- 材料类型：PLA（2466）、PETG（943）、ASA（526）、ABS（467）、TPU（312）。.. - 包括密度、直径、温度范围、颜色

• 所有内容均可在Spoolman用户界面中搜索

______________________________________________________________________

🔍 重型操作后的系统健康检查

用户： “既然斯波尔曼已经掌握了所有这些数据，沃罗号的装载情况如何？”

克劳德： 让我检查一下系统状态。..

┌──────────────────────────────────────┐
│ 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     │
└─────────────┴────────────┴───────────┘

分析： Spoolman在单独的机器上运行，因此5223根细丝不会影响Klipper。负载从1.71开始稳定→ 1.32 在初始索引之后。

______________________________________________________________________

🛠️ 配置审核和诊断

用户： “你能审计我的沃罗配置吗？”

克劳德： 我会分析你的打印机配置和日志。..

结果：

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 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驱动器优化

用户： “我的TMC驾驶员设置是什么，可以改进吗？”

克劳德： 让我检查一下您的TMC配置。..

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

______________________________________________________________________

📊 打印统计数据和耗材使用情况

用户： “显示我的打印统计数据和灯丝使用情况”

克劳德： 这是您的打印摘要。..

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%

______________________________________________________________________

🔄 多工具打印设置

用户： “我想打印一个双色模型，帮我设置工具”

克劳德： 让我来配置你的换刀器。..

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.

______________________________________________________________________

💾 更新前的自动备份

用户： “我想更新Klipper，但先备份我的配置”

克劳德： 我将创建一个备份，然后检查更新。..

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?

可选集成

斯波尔曼

通过设置启用灯丝跟踪 斯波尔曼:

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

然后更新 config.py:

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

TMC自动调谐

对于自动TMC调谐，请安装 klipper_tmc_自动调谐.

LED效果

对于动画LED，请安装 克利珀-勒德效应.

故障排除

服务器无法启动

# Check Moonraker is running
systemctl status moonraker

# Check logs
journalctl -u klipper-mcp -f

# Verify config
python3 -c "import config; print(config.MOONRAKER_URL)"

无法从VS代码连接

• 验证CB1/Pi IP地址是否正确
• 检查防火墙是否允许端口8000： sudo ufw allow 8000
• 验证VS Code和config.py中的API键匹配
• 测试： curl -H "X-API-Key: your-key" http://ip:8000/health

操作失败

• 检查 ARMED=True 用于危险操作
• 验证Klipper是否正在运行并准备就绪： systemctl status klipper
• 检查klippy.log： tail -f ~/printer_data/logs/klippy.log

斯波尔曼不工作

• 验证Spoolman是否正在运行： systemctl status spoolman
• 检查config.py中的URL是否与Spoolman的地址匹配
• 测试： curl http://localhost:7912/api/v1/health

项目结构

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

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 如果适用，添加测试
4. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

致谢

• Klipper -3D打印机固件
• 月光 -Klipper API服务器
• 模型上下文协议 -AI工具协议
• 隐形转换器 -换刀系统
• 斯波尔曼 -长丝管理