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