Moonraker MCP

A Moonraker component and MCP (Model Context Protocol) server for the E3CNC UI project.

What's inside

This package contains two things:

CNC Agent

The CNC agent owns CNC-specific state that Klipper does not model:

• spindle state and control (state, rpm, override)
• coolant state and control (flood, mist)
• units tracking (G20/G21)
• active work coordinate system (G54..G59, G53) and per-WCS offsets
• safe jog / set-zero / WCS-select command endpoints
• CNC dashboard settings persistence (separate from Mainsail's settings)
• machine profile loading for capability/safety/frontend feature gating

It registers HTTP endpoints under /server/cnc/*:

Read-only Klipper machine state is not re-exposed — the frontend reads it directly from Mainsail's existing websocket store subscription.

MCP Server

The MCP server connects to a running Moonraker instance and exposes 13 tools that AI agents can call.

13 Exposed MCP Tools

Running the MCP server

Option A — install from PyPI (recommended):

pip install moonraker-mcp
moonraker-mcp

Option B — install from source:

cd E3CNC/moonraker-mcp
pip install -e .
moonraker-mcp

Option C — run directly (no install):

cd E3CNC/moonraker-mcp
PYTHONPATH=src python -m moonraker_mcp.mcp_server

Environment variables

Connecting to AI Agents

The MCP server uses stdio transport — it communicates via stdin/stdout. Register it in your AI agent's MCP configuration.

Claude Desktop

Add to claude_desktop_config.json (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "moonraker": {
      "command": "moonraker-mcp",
      "args": [],
      "env": {
        "MOONRAKER_URL": "http://192.168.1.100:7125"
      }
    }
  }
}

If you didn't pip install -e ., use the full Python path:

{
  "mcpServers": {
    "moonraker": {
      "command": "/usr/bin/python3",
      "args": ["-m", "moonraker_mcp.mcp_server"],
      "env": {
        "MOONRAKER_URL": "http://192.168.1.100:7125"
      }
    }
  }
}

Cursor

Go to Settings → MCP → Add New MCP Server and fill in:

• Name: moonraker
• Type: command
• Command: moonraker-mcp
• Env (optional): MOONRAKER_URL=http://192.168.1.100:7125

Or add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "moonraker": {
      "command": "moonraker-mcp",
      "args": [],
      "env": {
        "MOONRAKER_URL": "http://192.168.1.100:7125"
      }
    }
  }
}

VS Code (Continue extension)

Add to ~/.continue/config.json:

{
  "experimental": {
    "mcpServers": [
      {
        "name": "moonraker",
        "command": "moonraker-mcp",
        "env": {
          "MOONRAKER_URL": "http://192.168.1.100:7125"
        }
      }
    ]
  }
}

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "moonraker": {
      "command": "moonraker-mcp",
      "env": {
        "MOONRAKER_URL": "http://192.168.1.100:7125"
      }
    }
  }
}

Any MCP-compatible agent

The pattern is always the same: register a subprocess that runs moonraker-mcp (or python -m moonraker_mcp.mcp_server) with MOONRAKER_URL set to your printer's Moonraker address.

Example AI prompts

Once connected, an AI agent can use the tools. Some examples:

"What's the printer status?" → calls moonraker_printer_info + moonraker_query_printer_objects

"Home all axes" → calls moonraker_send_gcode({ "script": "G28" })

"Set spindle to 12000 RPM clockwise" → calls moonraker_send_gcode({ "script": "M3 S12000" })

"Show the last 10 print jobs" → calls moonraker_history_list({ "limit": 10 })

"What webcams are configured?" → calls moonraker_webcams_list

"List all loaded Klipper objects" → calls moonraker_printer_objects_list

Network notes

• The MCP server runs on the same machine as the AI agent (your dev machine). It connects to Moonraker over HTTP.
• If Moonraker is on a different machine (the printer), set MOONRAKER_URL to the printer's IP (e.g. http://192.168.1.100:7125).
• Make sure your dev machine's IP is in Moonraker's trusted_clients list (in moonraker.conf).

Installing the CNC Agent on a Printer

Ansible playbook (recommended)

cd ~/E3CNC_UI
ansible-playbook ansible/playbooks/install.yml

This vendors the CNC agent into Moonraker, configures [cnc_agent] and [cnc_metadata] sections, deploys the WCS plugin and macros, builds the frontend, and restarts services.

Legacy bash script

cd ~/E3CNC_UI
./scripts/install_to_moonraker.sh

Updating via Moonraker Update Manager

The Ansible install and bash script both register an [update_manager E3CNC_UI] entry in moonraker.conf. After a git pull, the post_update_script automatically:

1. Downloads the latest pre-built frontend (avoids running vite build on the printer)
2. Re-vendors the CNC agent files into moonraker/components/
3. Re-deploys the metadata extractor, WCS plugin, and macros
4. Restarts Moonraker

Clicking Update in Mainsail's Machine → Update Manager panel is all you need.