kicad-mcp-server/docs/SCHEMATIC_TOOLS_REFERENCE.md

Schematic Tools Reference

Added in: v2.1.0, expanded in v2.2.0-v2.2.3 Contributors: @Mehanik (PRs #60, #66), @Kletternaut (PR #57)

This document provides a complete reference for the 27 schematic tools in the KiCAD MCP Server. These tools enable a complete schematic design workflow, from creating projects and adding components to wiring, validation, and synchronization with PCB boards. The dynamic symbol loading feature provides access to approximately 10,000 standard KiCad symbols.

Component Operations (8 tools)

add_schematic_component

Add a component to the schematic. Symbol format is 'Library:SymbolName' (e.g., 'Device:R', 'EDA-MCP:ESP32-C3').

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the schematic file
symbol	string	Yes	Symbol library:name reference (e.g., Device:R, EDA-MCP:ESP32-C3)
reference	string	Yes	Component reference (e.g., R1, U1)
value	string	No	Component value
footprint	string	No	KiCAD footprint (e.g. Resistor_SMD:R_0603_1608Metric)
position	object	No	Position on schematic with x and y coordinates

Usage Notes: The dynamic symbol loader provides access to ~10,000 KiCad standard symbols. If a symbol is not in the static template map, it will be loaded dynamically from the specified library.

delete_schematic_component

Remove a placed symbol from a KiCAD schematic (.kicad_sch). This removes the symbol instance (the placed component) from the schematic. It does NOT remove the symbol definition from lib_symbols. Note: This tool operates on schematic files (.kicad_sch). To remove a footprint from a PCB, use delete_component instead.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
reference	string	Yes	Reference designator of the component to remove (e.g. R1, U3)

edit_schematic_component

Update properties of a placed symbol in a KiCAD schematic (.kicad_sch) in-place. Use this tool to assign or update a footprint, change the value, or rename the reference of an already-placed component. This is more efficient than delete + re-add because it preserves the component's position and UUID. Note: operates on .kicad_sch files only. To modify a PCB footprint use edit_component.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
reference	string	Yes	Current reference designator of the component (e.g. R1, U3)
footprint	string	No	New KiCAD footprint string (e.g. Resistor_SMD:R_0603_1608Metric)
value	string	No	New value string (e.g. 10k, 100nF)
newReference	string	No	Rename the reference designator (e.g. R1 → R10)
fieldPositions	object	No	Reposition field labels: map of field name to {x, y, angle} (e.g. {"Reference": {"x": 12.5, "y": 17.0}})

get_schematic_component

Get full component info from a schematic: position, field values, and each field's label position (at x/y/angle). Use this to inspect or prepare repositioning of Reference/Value labels.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
reference	string	Yes	Component reference designator (e.g. R1, U1)

list_schematic_components

List all components in a schematic with their references, values, positions, and pins. Essential for inspecting what's on the schematic before making edits.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
filter	object	No	Optional filters with libId and/or referencePrefix fields
filter.libId	string	No	Filter by library ID (e.g., 'Device:R')
filter.referencePrefix	string	No	Filter by reference prefix (e.g., 'R', 'C', 'U')

move_schematic_component

Move a placed symbol to a new position in the schematic.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
reference	string	Yes	Reference designator (e.g., R1, U1)
position	object	Yes	New position with x and y coordinates

rotate_schematic_component

Rotate a placed symbol in the schematic.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
reference	string	Yes	Reference designator (e.g., R1, U1)
angle	number	Yes	Rotation angle in degrees (0, 90, 180, 270)
mirror	enum	No	Optional mirror axis ("x" or "y")

annotate_schematic

Assign reference designators to unannotated components (R? → R1, R2, ...). Must be called before tools that require known references.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file

Wiring and Connections (8 tools)

add_wire

Add a wire connection in the schematic.

Parameter	Type	Required	Description
start	object	Yes	Start position with x and y coordinates
end	object	Yes	End position with x and y coordinates

add_schematic_connection

Connect two component pins with a wire. Use this for individual connections between components with different pin roles (e.g. U1.SDA → J3.2). WARNING: Do NOT use this in a loop to wire N passthrough pins — use connect_passthrough instead (single call, cleaner layout, far fewer tokens).

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the schematic file
sourceRef	string	Yes	Source component reference (e.g., R1)
sourcePin	string	Yes	Source pin name/number (e.g., 1, 2, GND)
targetRef	string	Yes	Target component reference (e.g., C1)
targetPin	string	Yes	Target pin name/number (e.g., 1, 2, VCC)

add_schematic_net_label

Add a net label to the schematic.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the schematic file
netName	string	Yes	Name of the net (e.g., VCC, GND, SIGNAL_1)
position	array	Yes	Position [x, y] for the label

connect_to_net

Connect a component pin to a named net.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the schematic file
componentRef	string	Yes	Component reference (e.g., U1, R1)
pinName	string	Yes	Pin name/number to connect
netName	string	Yes	Name of the net to connect to

Usage Notes: Creates a wire stub from the pin and places a net label at the stub endpoint. The stub direction follows the pin's outward angle. Default stub length is 2.54mm (0.1 inch, standard grid spacing).

connect_passthrough

Connects all pins of a source connector (e.g. J1) to matching pins of a target connector (e.g. J2) via shared net labels — pin N gets net '{netPrefix}_{N}'. Use this for FFC/ribbon cable passthrough adapters instead of calling connect_to_net for every pin.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the schematic file
sourceRef	string	Yes	Source connector reference (e.g. J1)
targetRef	string	Yes	Target connector reference (e.g. J2)
netPrefix	string	No	Net name prefix, e.g. 'CSI' → CSI_1, CSI_2 (default: PIN)
pinOffset	number	No	Add to pin number when building net name (default: 0)

Usage Notes: This is the most efficient way to wire passthrough adapters. For an N-pin connector, this replaces N individual connect_to_net calls with a single operation.

get_schematic_pin_locations

Returns the exact x/y coordinates of every pin on a schematic component. Use this before add_schematic_net_label to place labels correctly on pin endpoints.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the schematic file
reference	string	Yes	Component reference designator (e.g. U1, R1, J2)

delete_schematic_wire

Remove a wire from the schematic by start and end coordinates.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
start	object	Yes	Wire start position with x and y coordinates
end	object	Yes	Wire end position with x and y coordinates

delete_schematic_net_label

Remove a net label from the schematic.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
netName	string	Yes	Name of the net label to remove
position	object	No	Position to disambiguate if multiple labels with same name (x and y coordinates)

Net Analysis (4 tools)

get_net_connections

Get all connections for a named net.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the schematic file
netName	string	Yes	Name of the net to query

Usage Notes: Uses wire graph analysis to find all component pins connected to the specified net. Returns a list of {component, pin} pairs.

list_schematic_nets

List all nets in the schematic with their connections.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file

list_schematic_wires

List all wires in the schematic with start/end coordinates.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file

list_schematic_labels

List all net labels, global labels, and power flags in the schematic.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file

Schematic Creation and Export (5 tools)

create_schematic

Create a new schematic.

Parameter	Type	Required	Description
name	string	Yes	Schematic name
path	string	No	Optional path

export_schematic_svg

Export schematic to SVG format using kicad-cli.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
outputPath	string	Yes	Output SVG file path
blackAndWhite	boolean	No	Export in black and white

export_schematic_pdf

Export schematic to PDF format using kicad-cli.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
outputPath	string	Yes	Output PDF file path
blackAndWhite	boolean	No	Export in black and white

get_schematic_view

Return a rasterized image of the schematic (PNG by default, or SVG). Uses kicad-cli to export SVG, then converts to PNG via cairosvg. Use this for visual feedback after placing or wiring components.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch file
format	enum	No	Output format ("png" or "svg", default: png)
width	number	No	Image width in pixels (default: 1200)
height	number	No	Image height in pixels (default: 900)

generate_netlist

Generate a netlist from the schematic.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the schematic file

Usage Notes: Returns a complete netlist with component information (reference, value, footprint) and net connections (net name with all connected component/pin pairs).

Validation and Synchronization (3 tools)

run_erc

Runs the KiCAD Electrical Rules Check (ERC) on a schematic and returns all violations. Use after wiring to verify the schematic before generating a netlist.

Parameter	Type	Required	Description
schematicPath	string	Yes	Path to the .kicad_sch schematic file

Usage Notes: Returns violations categorized by severity (error, warning, info) with location coordinates. Essential for catching design errors before PCB layout.

sync_schematic_to_board

Import the schematic netlist into the PCB board — equivalent to pressing F8 in KiCAD (Tools → Update PCB from Schematic). MUST be called after the schematic is complete and before placing or routing components on the PCB. Without this step, the board has no footprints and no net assignments — place_component and route_pad_to_pad will produce an empty, unroutable board.

Parameter	Type	Required	Description
schematicPath	string	Yes	Absolute path to the .kicad_sch schematic file
boardPath	string	Yes	Absolute path to the .kicad_pcb board file

Usage Notes: This is the F8 equivalent. It synchronizes the schematic design to the PCB, creating footprints on the board and assigning nets. This step is critical in the workflow: design in schematic → sync_schematic_to_board → place and route on PCB.

Example Workflows

Basic Circuit Design

1. Create project: Use create_schematic to initialize a new schematic file
2. Add components: Use add_schematic_component to place resistors, capacitors, ICs, etc.
   • Example: Add a resistor with symbol: "Device:R", reference: "R1", value: "10k"
3. Wire components: Use add_schematic_connection to connect component pins
   • Or use connect_to_net to connect pins to named nets (VCC, GND, etc.)
4. Add net labels: Use add_schematic_net_label to label important signals
5. Validate: Run run_erc to check for electrical rule violations
6. Review: Use list_schematic_components and get_schematic_view to verify the design
7. Sync to PCB: Use sync_schematic_to_board to transfer the design to the PCB layout

FFC Passthrough Adapter

1. Add connectors: Place two FFC connectors using add_schematic_component
   • Example: J1 and J2, both 20-pin FFC connectors
2. Connect passthrough: Use connect_passthrough with sourceRef: "J1", targetRef: "J2", netPrefix: "CSI"
   • This single call connects all 20 pins (J1.1 ↔ J2.1 via CSI_1, J1.2 ↔ J2.2 via CSI_2, etc.)
3. Sync to board: Use sync_schematic_to_board to create the PCB layout
4. Verify: Use list_schematic_nets to confirm all connections are correct

Source Files

The schematic tools are implemented across the following source files:

• TypeScript (Tool Definitions):

  • /home/chris/MCP/KiCAD-MCP-Server/src/tools/schematic.ts - All 27 schematic tool definitions with parameter schemas and handlers

• Python (Backend Implementation):

  • /home/chris/MCP/KiCAD-MCP-Server/python/commands/component_schematic.py - ComponentManager class (add, delete, edit, list components with dynamic symbol loading)
  • /home/chris/MCP/KiCAD-MCP-Server/python/commands/connection_schematic.py - ConnectionManager class (wiring, net labels, passthrough, netlist generation)
  • /home/chris/MCP/KiCAD-MCP-Server/python/commands/wire_manager.py - WireManager class (low-level wire manipulation)
  • /home/chris/MCP/KiCAD-MCP-Server/python/commands/pin_locator.py - PinLocator class (pin location lookup and angle calculation)
  • /home/chris/MCP/KiCAD-MCP-Server/python/commands/dynamic_symbol_loader.py - DynamicSymbolLoader class (runtime symbol loading from KiCad libraries)