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:

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:

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

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