cnc-fluidnc MCP Server

An MCP (Model Context Protocol) server that lets Claude control a CNC router running FluidNC firmware. Ask Claude to check machine status, jog axes, run G-code, manage SD card files, backup configs, and create macros — all through natural language.

What It Does

Claude Desktop  ←—stdio/JSON-RPC—→  cnc-mcp-server  ←—WebSocket + HTTP—→  FluidNC ESP32
                                          |
                                     data/macros/
                                     data/backups/

27 MCP tools across 6 groups:

Group	Tools	Examples
Status (4)	`get_machine_status`, `get_system_info`, `get_machine_settings`, `get_gcode_state`	"What's the machine position?"
Motion (5)	`jog`, `home_axes`, `unlock_machine`, `set_zero`, `go_to_zero`	"Jog X 10mm right"
G-code (6)	`send_gcode`, `run_gcode_program`, `spindle_control`, `feed_hold`, `cycle_resume`, `soft_reset`	"Turn the spindle on at 10000 RPM"
SD Card (4)	`list_sd_files`, `upload_to_sd`, `delete_sd_file`, `run_sd_file`	"Upload this G-code to the SD card"
Config (3)	`backup_config`, `list_backups`, `restore_config`	"Backup the current config"
Macros (5)	`list_macros`, `save_macro`, `get_macro`, `run_macro`, `delete_macro`	"Create a probe-z macro"

Safety System

Commands are classified into 4 levels. Dangerous operations require an explicit confirm: true parameter — Claude will naturally show you a preview and ask before executing.

SAFE — executes immediately (status queries, reads)
CAUTION — executes with warning (jogging, homing)
DANGEROUS — preview only unless confirm: true (spindle on, rapid moves, running programs)
CRITICAL — preview + strong warning unless confirm: true (soft reset, config restore)

Setup

Prerequisites

Node.js 18+
Claude Desktop with MCP support
A CNC controller running FluidNC on your network

Install

git clone https://github.com/WhitneyDesignLabs/cnc-fluidnc-mcp.git
cd cnc-fluidnc-mcp
npm install
npm run build

Configure Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "cnc-fluidnc": {
      "command": "/usr/bin/node",
      "args": ["/path/to/cnc-fluidnc-mcp/build/index.js"],
      "env": {
        "FLUIDNC_HOST": "http://your-controller.local"
      }
    }
  }
}

Linux note: Claude Desktop v1.1.x has a known bug where it overwrites this config file, removing mcpServers. Workaround: chmod 444 ~/.config/Claude/claude_desktop_config.json after editing.

Restart Claude Desktop. Use the Chat tab (Cowork doesn't load custom MCP servers).

FluidNC API Notes

This server communicates with FluidNC through two channels — understanding this split is critical:

Channel	Used For	Examples
WebSocket `ws://host:80/`	G-code, realtime commands	`G0 X50`, `M3 S10000`, `?`, `!`
HTTP `/command?plain=`	ESP3D commands, Grbl $ commands	`[ESP800]`, `$G`, `$H`, `$$`

SD card has its own endpoints (not the same as the flash filesystem):

Endpoint	Storage	Size
`/upload`	SD card	GBs — your G-code files
`/files`	ESP32 flash	~170KB — WebUI, config

G-code sent via HTTP plain= is silently ignored. This is the #1 gotcha when integrating with FluidNC.

Tested With

FluidNC v4.0.2 on MKS TinyBee V1.0
ESP32 (2 cores, 240MHz, 8MB flash)
14.83 GB FAT32 SD card
Claude Desktop v1.1.8629 on Ubuntu Linux

Should work with other FluidNC-based boards (MKS DLC32, 6-Pack, etc.) — the API is the same.

Development

npm run watch    # Rebuild on changes
npm run build    # One-time build
npm start        # Run the server directly

License

MIT

cnc-fluidnc-mcp