CNCjs MCP Server

MCP server bridging Claude Code to CNCjs for GRBL CNC control (FoxAlien XE Ultra).

Architecture

Claude Code ←stdio/MCP→ cncjs-mcp (Node.js) ←Socket.IO v1→ CNCjs :8000 ←USB Serial→ GRBL

Tools (56 total)

Read-Only / Query (17)

list_serial_ports, get_connection_status, get_machine_state, get_machine_position, get_work_coordinate_offset, get_machine_settings, get_parser_state, get_loaded_gcode, get_job_progress, get_workflow_state, get_feeder_status, list_macros, list_machines, get_alarm_info, get_console_output, get_error_info, analyze_gcode

Connection (2)

connect_to_port, disconnect_port

Control (16)

send_gcode, load_gcode, start_job, pause_job, resume_job, stop_job, home_machine, unlock_machine, jog, set_feed_override, set_spindle_override, set_work_zero, spindle_control, coolant_control, set_wcs, probe_z

Safety (3)

emergency_stop (soft reset 0x18), feed_hold, jog_cancel

Management (1)

run_macro

G-code Generation (4)

generate_gcode_profile — cut 2D shapes (circle, rectangle, custom path) generate_gcode_pocket — clear rectangular or circular pockets generate_gcode_drill — drilling patterns (grid, circle, custom) with peck support generate_gcode_facing — surface facing/leveling

Design File Generation (2)

generate_svg — create SVG files for import into Carveco/Fusion 360 generate_dxf — create DXF R12 files for CAM software import

Fusion 360 Integration (2)

generate_fusion_script — generate Python API scripts for Fusion 360 (sketch, extrude, revolve, fillet, chamfer, export, CAM setup) list_fusion_scripts — list previously generated scripts

FreeCAD Integration (3)

generate_freecad_model — generate Python scripts for headless 3D modeling (box, cylinder, sphere, cone, sketch, extrude, boolean ops, export STEP/STL) generate_freecad_cam — generate CAM toolpath scripts with G-code export (profile, pocket, drill, face operations) list_freecad_scripts — list previously generated FreeCAD scripts

Adobe Illustrator Integration (3)

generate_illustrator_script — generate ExtendScript (.jsx) for vector artwork (rectangle, circle, polygon, star, text, paths, export to SVG/DXF/PDF) generate_illustrator_export_script — batch export current document to SVG/DXF/PDF/EPS with text-to-outlines option list_illustrator_scripts — list previously generated Illustrator scripts

Marketplace & Packaging (3)

package_design — bundle designs into marketplace-ready packages (multi-format files, preview images, README, listing metadata, zip archive) generate_listing_description — generate SEO-optimized listing descriptions for Etsy, Cults3D, or Gumroad convert_design_format — convert between formats (SVG↔DXF, G-code→SVG preview)

Windows PC Setup for CNCjs

1. Node.js (LTS recommended, v18+) — download from https://nodejs.org

2. CNCjs — install via npm after Node.js is set up:

   npm install -g cncjs
   

   Or download the desktop app installer from the CNCjs GitHub releases page.

3. USB/Serial driver for your FoxAlien XE Ultra — likely one of:

   • CH340 driver (most common on FoxAlien boards) — download from the manufacturer site
   • CP210x driver (if it uses a SiLabs chip)
   • Windows 10/11 may auto-install these, but if your board doesn't show up in Device Manager under "Ports (COM & LPT)", install the driver manually

Quick start after install:

cncjs

Then open http://localhost:8000 in your browser. Your FoxAlien will show up as a COM port (e.g., COM3). Select it, set baud rate to 115200, controller type Grbl, and connect.

Optional but recommended:

• Chrome/Edge — CNCjs web UI works best in Chromium browsers
• Python (sometimes needed for node-gyp native module builds during npm install)

MCP Server Setup

npm install
npm run build

Register with Claude Code:

claude mcp add cncjs-mcp node /path/to/cncjs-mcp/build/index.js

Environment Variables

• CNCJS_URL — CNCjs server URL (default: http://localhost:8000)
• CNCJS_TOKEN — Optional JWT token for CNCjs authentication