Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cnc-fluidnc-mcp Home all axes and then tell me the current machine position."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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) |
| "What's the machine position?" |
Motion (5) |
| "Jog X 10mm right" |
G-code (6) |
| "Turn the spindle on at 10000 RPM" |
SD Card (4) |
| "Upload this G-code to the SD card" |
Config (3) |
| "Backup the current config" |
Macros (5) |
| "Create a probe-z macro" |
Related MCP server: CNCjs MCP Server
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)
Node.js 18+
Claude Desktop with MCP support
A CNC controller running FluidNC on your network
git clone https://github.com/WhitneyDesignLabs/cnc-fluidnc-mcp.git
cd cnc-fluidnc-mcp
npm install
npm run buildAdd 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.jsonafter editing.
Restart Claude Desktop. Use the Chat tab (Cowork doesn't load custom MCP servers).
This server communicates with FluidNC through two channels — understanding this split is critical:
Channel | Used For | Examples |
WebSocket | G-code, realtime commands |
|
HTTP | ESP3D commands, Grbl $ commands |
|
SD card has its own endpoints (not the same as the flash filesystem):
Endpoint | Storage | Size |
| SD card | GBs — your G-code files |
| ESP32 flash | ~170KB — WebUI, config |
G-code sent via HTTP plain= is silently ignored. This is the #1 gotcha when integrating with FluidNC.
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.
npm run watch # Rebuild on changes
npm run build # One-time build
npm start # Run the server directlyMIT
Save the current FluidNC settings and work offsets to a timestamped backup file.
Inputs: description.
Resume machine motion after a feed hold. Sends '~' realtime command.
Inputs: no named parameters.
Delete a saved macro. Requires confirm=true.
Inputs: name (required), confirm.
Delete a file from the CNC controller's SD card. Requires confirm=true.
Inputs: filepath (required), confirm.
Pause machine motion immediately (feed hold). Sends '!' realtime command.
Inputs: no named parameters.
Get active G-code modal state: motion mode, coordinate system, units, distance mode, spindle, coolant
Inputs: no named parameters.
Get all FluidNC/Grbl machine settings. Optionally filter by keyword (e.g. 'accel', 'steps', 'max_rate').
Inputs: filter.
Get real-time CNC machine status: position, state, feed rate, spindle speed, and overrides
Inputs: no named parameters.
View the contents of a saved macro.
Inputs: name (required).
Get FluidNC system information: firmware version, CPU, memory, WiFi, SD card status
Inputs: no named parameters.
Move to work coordinate zero. Raises Z to safe height first, then moves XY, then lowers Z.
Inputs: safeZ, feedRate, confirm.
Run homing cycle. Homes all axes by default, or specify individual axes.
Inputs: axes.
Jog the CNC machine along an axis by a specified distance at a given feed rate. Uses incremental mode ($J=G91).
Inputs: axis (required), distance (required), feedRate.
List all saved configuration backups.
Inputs: no named parameters.
List all saved CNC macros.
Inputs: no named parameters.
List files and directories on the CNC controller's SD card.
Inputs: path.
Restore machine settings from a backup. Defaults to dry-run mode showing what would change. Requires confirm=true to actually apply.
Inputs: filename (required), confirm.
Send a multi-line G-code program to the machine, one line at a time. Requires confirm=true.
Inputs: gcode (required), confirm.
Execute a saved macro. Shows preview first; set confirm=true to run. Parameters can override defaults.
Inputs: name (required), params, confirm.
Run a G-code file from the CNC controller's SD card. Requires confirm=true.
Inputs: filepath (required), confirm.
Create or update a macro. Parameters can be substituted in G-code using {param_name} syntax.
Inputs: name (required), description (required), gcode (required), parameters.
Send a single G-code or Grbl command to the CNC machine. Safety level is auto-classified. DANGEROUS/CRITICAL commands require confirm=true.
Inputs: command (required), confirm.
Set the work coordinate zero for specified axes at the current position (G10 L20 P1). If no axes specified, sets all axes to zero.
Inputs: axes.
Emergency stop — soft reset the controller (0x18). Stops all motion and spindle immediately. Requires confirm=true.
Inputs: confirm.
Control the spindle: turn on (CW/CCW with speed) or off. Turning on requires confirm=true.
Inputs: action (required), speed, confirm.
Clear alarm state and unlock the machine ($X). Use after an alarm condition.
Inputs: no named parameters.
Upload a file to the CNC controller's SD card.
Inputs: filename (required), content (required), path.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 27 tools
Each tool has a clearly distinct purpose with no significant overlap. For example, backup_config, restore_config, and list_backups are distinct operations for configuration management, while send_gcode, run_gcode_program, and run_sd_file handle different G-code execution methods. The descriptions clearly differentiate actions like jog (manual movement) versus go_to_zero (automated positioning).
Tool names follow a highly consistent verb_noun pattern throughout, such as get_machine_status, list_sd_files, run_gcode_program, and delete_macro. All tools use snake_case without deviation, and verbs like get, list, run, send, set, and delete are applied predictably across related operations, making the set easy to navigate.
With 27 tools, the count is on the higher side but reasonable given the comprehensive scope of CNC machine control. It covers diverse aspects like configuration, motion control, file management, and safety operations. While slightly heavy, each tool appears justified for the domain, avoiding redundancy and supporting complex workflows.
The tool set provides complete coverage for CNC machine operations, including configuration backup/restore, real-time status monitoring, G-code execution, file management, macro handling, motion control, and safety features. There are no obvious gaps; it supports full lifecycle management from setup to execution and troubleshooting, ensuring agents can handle typical tasks without dead ends.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
