# cnc-fluidnc MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets Claude control a CNC router running [FluidNC](https://github.com/bdring/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](https://claude.ai/download) with MCP support
- A CNC controller running [FluidNC](https://github.com/bdring/FluidNC) on your network

### Install

```bash
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):

```json
{
  "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](https://github.com/anthropics/claude-code/issues/32345) 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

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

## License

MIT