kicad-mcp-server/docs/ROUTING_TOOLS_REFERENCE.md

Routing Tools Reference

Added in: v1.0.0, major expansion in v2.2.0-v2.2.3 (PR #44, @Kletternaut)

This document provides comprehensive documentation for the 13 routing tools available in the KiCAD MCP Server. These tools cover basic trace routing, advanced operations like differential pairs, net management, trace operations, and copper zone management.

Basic Routing (3 tools)

add_net

Create a new net on the PCB.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Net name
netClass	string	No	Net class name

Usage Notes:

• Creates a new net that can be assigned to traces and pads
• If the net already exists, it will be reused
• Net class assignment is optional; defaults to "Default" if not specified

Example:

{
  "name": "VCC_3V3",
  "netClass": "Power"
}

---

route_trace

Route a trace segment between two XY points on a fixed layer.

Parameters:

Parameter	Type	Required	Description
start	object	Yes	Start position with x, y, and optional unit
end	object	Yes	End position with x, y, and optional unit
layer	string	Yes	PCB layer
width	number	Yes	Trace width in mm
net	string	Yes	Net name

Usage Notes:

• WARNING: Does NOT handle layer changes
• If start and end are on different copper layers, use route_pad_to_pad instead, which automatically inserts a via
• Coordinates use mm by default unless unit is specified
• This is a low-level tool; prefer route_pad_to_pad for component-to-component routing

Example:

{
  "start": {"x": 100.0, "y": 50.0, "unit": "mm"},
  "end": {"x": 120.0, "y": 50.0, "unit": "mm"},
  "layer": "F.Cu",
  "width": 0.25,
  "net": "GND"
}

---

route_pad_to_pad

PREFERRED tool for pad-to-pad routing. Looks up pad positions automatically, detects the net from the pad, and automatically inserts a via if the two pads are on different copper layers.

Parameters:

Parameter	Type	Required	Description
fromRef	string	Yes	Reference of the source component (e.g. 'U2')
fromPad	string/number	Yes	Pad number on the source component (e.g. '6' or 6)
toRef	string	Yes	Reference of the target component (e.g. 'U1')
toPad	string/number	Yes	Pad number on the target component (e.g. '15' or 15)
layer	string	No	PCB layer (default: F.Cu)
width	number	No	Trace width in mm (default: board default)
net	string	No	Net name override (default: auto-detected from pad)

Usage Notes:

• This is the PREFERRED tool for routing between component pads
• Automatically looks up pad positions - no need to query them separately
• Auto-detects the net from the source pad
• Critically: if pads are on different copper layers (e.g., one on F.Cu and one on B.Cu), automatically inserts a via at an appropriate position to complete the connection
• Always use this instead of route_trace when routing between named component pads
• Via is placed at the start pad's X coordinate to avoid stacking issues with back-to-back mirrored connectors

Example:

{
  "fromRef": "U2",
  "fromPad": "6",
  "toRef": "U1",
  "toPad": "15",
  "width": 0.25
}

---

Vias (1 tool)

add_via

Add a via to the PCB.

Parameters:

Parameter	Type	Required	Description
position	object	Yes	Via position with x, y, and optional unit
net	string	Yes	Net name
viaType	string	No	Via type: "through", "blind", or "buried"

Usage Notes:

• Through vias connect all layers (default)
• Blind vias connect an outer layer to one or more inner layers
• Buried vias connect two or more inner layers without reaching outer layers
• Position coordinates use mm by default

Example:

{
  "position": {"x": 110.0, "y": 50.0, "unit": "mm"},
  "net": "GND",
  "viaType": "through"
}

---

Advanced Routing (2 tools)

route_differential_pair

Route a differential pair between two sets of points.

Parameters:

Parameter	Type	Required	Description
positivePad	object	Yes	Positive pad with reference and pad number
negativePad	object	Yes	Negative pad with reference and pad number
layer	string	Yes	PCB layer
width	number	Yes	Trace width in mm
gap	number	Yes	Gap between traces in mm
positiveNet	string	Yes	Positive net name
negativeNet	string	Yes	Negative net name

Usage Notes:

• Used for high-speed signals like USB, Ethernet, HDMI, etc.
• Maintains controlled impedance through consistent trace width and gap
• Both traces are routed in parallel with specified separation
• Pad object format: {"reference": "U1", "pad": "1"}

Example:

{
  "positivePad": {"reference": "J1", "pad": "2"},
  "negativePad": {"reference": "J1", "pad": "3"},
  "layer": "F.Cu",
  "width": 0.2,
  "gap": 0.2,
  "positiveNet": "USB_DP",
  "negativeNet": "USB_DN"
}

---

copy_routing_pattern

Copy routing pattern (traces and vias) from a group of source components to a matching group of target components.

Parameters:

Parameter	Type	Required	Description
sourceRefs	array[string]	Yes	References of the source components (e.g. ['U1', 'R1', 'C1'])
targetRefs	array[string]	Yes	References of the target components in same order as sourceRefs (e.g. ['U2', 'R2', 'C2'])
includeVias	boolean	No	Also copy vias (default: true)
traceWidth	number	No	Override trace width in mm (default: keep original width)

Usage Notes:

• The offset is calculated automatically from the position difference between the first source and first target component
• Useful for replicating routing between identical circuit blocks
• Component arrays must be in matching order (sourceRefs[0] maps to targetRefs[0], etc.)
• Preserves relative routing topology from source to target
• Vias are copied by default unless includeVias is set to false
• Original trace widths are preserved unless traceWidth override is specified

Example:

{
  "sourceRefs": ["U1", "R1", "C1"],
  "targetRefs": ["U2", "R2", "C2"],
  "includeVias": true
}

---

Net Management (2 tools)

get_nets_list

Get a list of all nets in the PCB with optional statistics.

Parameters:

Parameter	Type	Required	Description
includeStats	boolean	No	Include statistics (track count, total length, etc.)
unit	string	No	Unit for length measurements: "mm" or "inch"

Usage Notes:

• Returns all nets present in the board
• Statistics include track count, via count, and total trace length
• Useful for verifying net connectivity and routing completeness
• Length measurements default to mm

Example:

{
  "includeStats": true,
  "unit": "mm"
}

---

create_netclass

Create a new net class with custom design rules.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Net class name
traceWidth	number	No	Default trace width in mm
clearance	number	No	Clearance in mm
viaDiameter	number	No	Via diameter in mm
viaDrill	number	No	Via drill size in mm

Usage Notes:

• Net classes define design rules for groups of nets
• Common use cases: power nets (wider traces), high-speed signals (controlled impedance)
• Once created, assign nets to the class using the netClass parameter in add_net
• All measurements in mm

Example:

{
  "name": "Power",
  "traceWidth": 0.5,
  "clearance": 0.3,
  "viaDiameter": 0.8,
  "viaDrill": 0.4
}

---

Trace Operations (3 tools)

delete_trace

Delete traces from the PCB. Can delete by UUID, position, or bulk-delete all traces on a net.

Parameters:

Parameter	Type	Required	Description
traceUuid	string	No	UUID of a specific trace to delete
position	object	No	Delete trace nearest to this position (x, y, optional unit)
net	string	No	Delete all traces on this net (bulk delete)
layer	string	No	Filter by layer when using net-based deletion
includeVias	boolean	No	Include vias in net-based deletion

Usage Notes:

• Three deletion modes: by UUID (specific), by position (nearest), or by net (bulk)
• Position-based deletion finds the closest trace to the specified coordinates
• Net-based deletion can be filtered by layer
• Vias are excluded from net-based deletion by default unless includeVias is true

Example (bulk delete):

{
  "net": "GND",
  "layer": "F.Cu",
  "includeVias": false
}

---

query_traces

Query traces on the board with optional filters by net, layer, or bounding box.

Parameters:

Parameter	Type	Required	Description
net	string	No	Filter by net name
layer	string	No	Filter by layer name
boundingBox	object	No	Filter by bounding box region (x1, y1, x2, y2, optional unit)
unit	string	No	Unit for coordinates: "mm" or "inch"

Usage Notes:

• Returns trace information including UUID, position, width, layer, and net
• Filters can be combined (e.g., specific net on specific layer)
• Bounding box uses rectangular region defined by opposite corners
• Useful for analyzing routing in specific board regions or on specific nets

Example:

{
  "net": "VCC_3V3",
  "layer": "F.Cu"
}

---

modify_trace

Modify an existing trace (change width, layer, or net).

Parameters:

Parameter	Type	Required	Description
traceUuid	string	Yes	UUID of the trace to modify
width	number	No	New trace width in mm
layer	string	No	New layer name
net	string	No	New net name

Usage Notes:

• Requires the trace UUID, which can be obtained from query_traces
• At least one modification parameter (width, layer, or net) must be provided
• Use with caution when changing nets - ensure electrical correctness
• Width changes are useful for adjusting impedance or current capacity

Example:

{
  "traceUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "width": 0.5
}

---

Copper Zones (2 tools)

add_copper_pour

Add a copper pour (ground/power plane) to the PCB.

Parameters:

Parameter	Type	Required	Description
layer	string	Yes	PCB layer
net	string	Yes	Net name
clearance	number	No	Clearance in mm
outline	array[object]	No	Array of {x, y} points defining the pour boundary. If omitted, the board outline is used.

Usage Notes:

• Copper pours are typically used for ground and power planes
• If no outline is specified, the pour fills the entire board area
• Custom outlines are defined as arrays of coordinate points
• Clearance defines the minimum distance from other copper features
• After adding a pour, use refill_zones to fill it

Example:

{
  "layer": "B.Cu",
  "net": "GND",
  "clearance": 0.2,
  "outline": [
    {"x": 10.0, "y": 10.0},
    {"x": 90.0, "y": 10.0},
    {"x": 90.0, "y": 60.0},
    {"x": 10.0, "y": 60.0}
  ]
}

---

refill_zones

Refill all copper zones on the board.

Parameters:

None

Usage Notes:

• WARNING: SWIG path has known segfault risk (see KNOWN_ISSUES.md)
• Prefer using IPC backend (KiCAD open) or triggering zone fill via KiCAD UI instead
• Required after adding or modifying copper pours to calculate the filled areas
• Recalculates all zone fills based on current board state
• May take several seconds on complex boards with many zones

Example:

{}

---

Example Workflows

Point-to-Point Routing with route_pad_to_pad

The simplest and most robust approach for connecting component pads:

// Connect pin 1 of U1 to pin 5 of R1
{
  "tool": "route_pad_to_pad",
  "params": {
    "fromRef": "U1",
    "fromPad": "1",
    "toRef": "R1",
    "toPad": "5",
    "width": 0.25
  }
}

This automatically:

• Looks up the exact pad positions
• Detects the net from the pads
• Creates the trace on the appropriate layer
• Inserts a via if the pads are on different copper layers

Differential Pair Routing (USB, Ethernet)

For high-speed differential signals like USB D+ and D-:

// 1. Create nets if needed
{
  "tool": "add_net",
  "params": {"name": "USB_DP"}
}
{
  "tool": "add_net",
  "params": {"name": "USB_DN"}
}

// 2. Route the differential pair
{
  "tool": "route_differential_pair",
  "params": {
    "positivePad": {"reference": "U1", "pad": "14"},
    "negativePad": {"reference": "U1", "pad": "15"},
    "layer": "F.Cu",
    "width": 0.2,
    "gap": 0.2,
    "positiveNet": "USB_DP",
    "negativeNet": "USB_DN"
  }
}

Replicating Routing Patterns

For repeated circuit blocks (e.g., multiple identical LED drivers):

// Route the first instance (U1, R1, C1) manually, then copy to others
{
  "tool": "copy_routing_pattern",
  "params": {
    "sourceRefs": ["U1", "R1", "C1"],
    "targetRefs": ["U2", "R2", "C2"],
    "includeVias": true
  }
}

// Copy the same pattern to a third instance
{
  "tool": "copy_routing_pattern",
  "params": {
    "sourceRefs": ["U1", "R1", "C1"],
    "targetRefs": ["U3", "R3", "C3"],
    "includeVias": true
  }
}

Adding a Ground Plane

// 1. Create the copper pour on bottom layer
{
  "tool": "add_copper_pour",
  "params": {
    "layer": "B.Cu",
    "net": "GND",
    "clearance": 0.2
  }
}

// 2. Fill the zones
{
  "tool": "refill_zones",
  "params": {}
}

Note: Use the IPC backend (keep KiCAD open) when using refill_zones to avoid potential segfaults with the SWIG backend.

---

Source Files

• TypeScript Tool Definitions: /home/chris/MCP/KiCAD-MCP-Server/src/tools/routing.ts
• Python Implementation: /home/chris/MCP/KiCAD-MCP-Server/python/commands/routing.py