MCP Server

From version 2.0.2 on, freeRouting can be driven by an AI assistant through the Model Context Protocol (MCP). Started with --mcp, the program is itself the MCP server. The host, for example Cursor, Claude Desktop or Claude Code, starts the freeRouting binary as a child process and talks JSON-RPC over its standard input and output, one message per line. There is no port, no socket and no web server, so nothing has to be opened in a firewall.

The options have the same names as in the LayoutEditor. Without --mcp the program behaves as before: no MCP code runs, and standard output belongs to the normal messages.

Window or no window

--mcp alone keeps the window hidden. The router works on the same board, rules and settings as in the window, but no window appears on the screen. This is the usual mode for an assistant.

--mcp --mcpgui shows the board window. You watch the router while the assistant drives it, and you can work in the window yourself between two requests. Without --mcp the option --mcpgui is ignored, with a note on the error output.

A design can be opened at the start with -de and the file name, and --angle sets its trace angle (90, 45 or any). Without -de the server starts empty and the assistant opens a design with fr_open_design. With --mcpgui the window appears as soon as a design is open.

freeRouting --mcp
freeRouting --mcp --mcpgui
freeRouting --mcp -de board.dsn --angle 45

On Linux without a display (no DISPLAY and no WAYLAND_DISPLAY), --mcp selects the Qt platform offscreen, unless -platform or QT_QPA_PLATFORM already names one. -h still prints the help on standard output, also next to --mcp.

Host configuration

All hosts use the same form: a server name, the path of the freeRouting binary and the argument --mcp. Add --mcpgui to the arguments if you want to see the window. The binary is part of the LayoutEditor package, see Getting FreeRouting.

Linux, from the package or built from source:

{
  "mcpServers": {
    "freerouting": {
      "command": "/path/to/LayoutEditor/bin/freeRouting",
      "args": ["--mcp"]
    }
  }
}

Windows. The binary is a window application, so the host has to start it with pipes, as all MCP hosts do. Started by a double click it has no standard input and stops with a message.

{
  "mcpServers": {
    "freerouting": {
      "command": "C:\\path\\to\\LayoutEditor\\bin\\freeRouting.exe",
      "args": ["--mcp"]
    }
  }
}

macOS. The command is the binary inside the application bundle, not the bundle itself.

{
  "mcpServers": {
    "freerouting": {
      "command": "/Applications/LayoutEditor.app/Contents/MacOS/freeRouting",
      "args": ["--mcp", "--mcpgui"]
    }
  }
}

Cursor reads this from .cursor/mcp.json in the project or from the user configuration. Claude Desktop uses the same mcpServers block in its configuration file. Claude Code adds the server on the command line:

claude mcp add freerouting -- /path/to/LayoutEditor/bin/freeRouting --mcp

Tools

Tool Purpose
fr_session_info version, window mode, Qt platform, open design, whether the autorouter runs
fr_open_design open a dsn or bin file, optional trace angle; returns the board summary
fr_close_design close the design without saving
fr_board_summary unit, bounding box, layers, nets, net classes, items by type, incompletes, clearance violations, angle, postroute
fr_board_items items with id, type, nets, layers, bounding box and fixed flag; filter by type or net, with offset and limit
fr_autoroute run the batch autorouter, optional angle and postroute; answers when the router is done
fr_stop stop a running autoroute; the routes found so far stay
fr_write_ses write the Specctra session file, by default next to the design
fr_screenshot PNG of the board view, optional zoom to the whole board

A typical session opens the dsn file that the board editor exported, reads the summary, runs the autorouter and writes the ses file. The board editor then reads the session back, as described for LayoutEditor, KiCad and Eagle. Coordinates in the answers are in the unit of the design, which the summary names.

fr_autoroute is the same batch run as the Autorouting button and --autoroute. It runs on its own thread, and the answer comes when the router has finished. The answer gives the time, the incompletes before and after, the clearance violations and the number of traces and vias. While it runs, fr_session_info, fr_screenshot and fr_stop are answered at once. Other requests wait until the router is done. A cancel from the host (notifications/cancelled) stops the router like fr_stop. With postroute set to false, the route optimizer is skipped, as with --no-postroute. Without postroute the current setting stays.

In the hidden mode fr_screenshot takes width and height for the size of the view. With --mcpgui the picture is the window as you see it.

End of a session

When the host closes the standard input, the hidden server stops. A running autoroute is stopped first, and after five seconds the process ends in any case. With --mcpgui the window stays open for you, and closing it ends the program. If no design was open, the visible server ends like the hidden one.

Protocol

The server speaks protocol version 2026-07-28: the host calls server/discover, or names the version in each request under _meta. The handshake with initialize stays valid for 2025-06-18, 2025-03-26 and 2024-11-05. ping is answered also while the router runs.

The source tree contains a test that drives a whole session with and without the window:

python3 tools/freeRouting2/verify/mcp_smoke.py
python3 tools/freeRouting2/verify/mcp_smoke.py --gui