kicad-mcp
This server exposes a local MCP interface to inspect and control a running KiCad PCB editor, with a set of read, edit, and fabrication tools.
Inspect the PCB: Check connection (
kicad_status), read board info (get_board_info), board layers (get_board_layers), stackup (get_board_stackup), and current selection (get_selection).Query components and nets: List footprints (
list_footprints), nets (list_nets), pads, vias, zones, and detailed items by UUID (get_item_details).Generate bills of materials: Read or export a grouped/ungrouped BOM with custom fields, DNP/excluded filtering, and CSV output (
get_bom,export_bom).Edit the board: Add text (
add_text), create/delete vias, adjust layers, delete items, and trigger asynchronous zone refills.Run design rule checks and fabrication exports: Use
kicad-clito run DRC and export Gerbers, drill files, component positions, and SVG from a copied board snapshot.Control server mode: Launch over HTTP or stdio, with optional read-only mode exposing only the 15 inspection/BOM tools, and manage lifecycle via KiCad plugin actions or CLI commands.
Allows MCP clients to interact with an open KiCad PCB editor, providing tools for reading board information, footprints, nets, tracks, selections, and BOM data, as well as editing operations such as moving footprints, adding tracks/text, updating BOM fields, and saving the board.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kicad-mcp List the footprints on the current board"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
KiCad MCP — HackInvent
A KiCad 10+ plugin that starts a Model Context Protocol server, letting MCP-compatible assistants work with the open PCB.
The plugin uses KiCad’s official IPC API and the kicad-python library, without pcbnew/SWIG bindings. It provides two actions: Start MCP server and Stop MCP server. A stdio mode also lets an MCP client launch the server directly.
Version 0.3.1, alpha. The MCP protocol, server lifecycle and operations are covered by automated tests. The KiCad tests use real kicad-python objects with a simulated editor; validation in a real KiCad interface is still pending. This project targets the PCB editor and requires a running GUI instance.
Available tools
MCP tool | Function |
| Check the connection and KiCad version |
| Read the board name, layers and item counts |
| Read references, values, positions, rotations and lock status; optional exact reference filter |
| List electrical nets |
| Read straight and curved tracks, their dimensions and nets |
| Read the items selected in the editor |
| Inspect pad numbers, parent references, positions, nets and geometry; filter by reference or net |
| Inspect via dimensions, layer spans and nets |
| Inspect zone names, nets, layers, priorities and fill state |
| Retrieve type-specific details for exact item UUIDs |
| Inspect enabled layers, display names, visibility and the active layer |
| Read ordered copper/dielectric layers, thicknesses, materials and finish settings |
| List the pads, tracks and vias assigned to one net |
| Read a grouped or individual-component BOM from the open PCB |
| Return the PCB BOM as CSV text to the MCP client |
| Move a component by its reference and optionally rotate it |
| Add a straight track on an enabled copper layer |
| Add text to the board |
| Update component values, custom BOM fields and assembly flags |
| Replace, add to or remove from the editor selection using item UUIDs |
| Activate an enabled layer by its canonical name |
| Set which enabled layers are visible |
| Add a through-hole via spanning F.Cu to B.Cu |
| Delete supported, unlocked top-level items by UUID in one undo step |
| Request an asynchronous zone refill in the editor |
| Check the last saved PCB with kicad-cli and create a local JSON report |
| Export Gerbers, drill files, component positions or SVG from the last saved PCB |
| Explicitly save the PCB to its current file |
There are 28 tools: 15 read tools and 13 tools that change the editor, save the PCB or create artifacts. BOM export reads the PCB and returns text; it does not write a file.
Distances are in millimetres, positions are absolute and angles are in degrees. MCP numeric arguments must be JSON numbers and flags must be JSON booleans; implicit conversion between these types is rejected. Object creation, movement, deletion and BOM updates create an undo step in KiCad. Selection and layer visibility change the editor view. Zone refill is a separate asynchronous KiCad action. These operations never trigger an automatic save. save_board also saves any other unsaved changes currently in the editor.
add_track creates a segment and add_via creates a through-hole via; neither performs autorouting or design-rule checks. Locked components and ambiguous references are rejected. Footprints containing items that kicad-python cannot safely transform are also rejected; pads, standard geometry and 3D models are supported.
Related MCP server: pcb-mcp
Inspect and edit a PCB
Use get_board_layers to discover canonical layer names such as F.Cu, B.Cu and Edge.Cuts. get_board_stackup reports board thickness and material information from Board Setup.
Call list_pads with {"reference": "U1"} to inspect a component, or get_net_connections with {"net_name": "GND"} to inspect all pads, tracks and vias assigned to a net. These lists describe net membership. They do not prove that the copper is physically connected or that the design passes DRC; the net response explicitly reports connectivity_verified: false.
Use UUIDs returned by inspection tools to request get_item_details or control selection. Item requests accept up to 500 unique UUIDs at a time:
{
"item_ids": ["REPLACE_WITH_AN_ITEM_UUID"],
"mode": "replace"
}set_selection also accepts "add" and "remove"; {"item_ids": [], "mode": "replace"} clears the selection. Layer tools accept canonical names: for example, call set_visible_layers with {"layers": ["F.Cu", "Edge.Cuts"]}.
To create a through-hole via assigned to an existing net, call add_via:
{
"x_mm": 25.0,
"y_mm": 30.0,
"diameter_mm": 0.6,
"drill_mm": 0.3,
"net_name": "GND"
}The drill must be smaller than the copper diameter. This tool supports through-hole vias only. Inspect the result and run DRC before using the board for manufacturing.
delete_items validates every requested UUID before deleting anything. It refuses locked items, footprint children such as pads and fields, and grouped items whose effective lock cannot be established through the API. Delete the parent footprint when appropriate, or ungroup items in KiCad first. A failed edit rolls back its transaction; an unconfirmed rollback is reported explicitly.
refill_zones schedules KiCad’s refill action and returns completed: false. Wait for the editor to finish before dependent edits or saving. The MCP response confirms that the action was requested, not that the fill finished.
Check DRC and export manufacturing files
These tools require kicad-cli from the same major KiCad version as the running editor. Put it on PATH or set KICAD_MCP_CLI to the executable’s full path before starting the server. They create local files and are unavailable in read-only mode.
Both tools use a private copy of the last saved PCB, along with saved project settings and custom design rules when available. Their responses identify this as snapshot: "last_saved_board" and includes_unsaved_changes: false. They never implicitly save the open PCB or project. Call save_board first to include pending PCB edits, and save changed project settings in KiCad before checking them. A never-saved PCB must first be saved in KiCad.
This choice avoids an effect of KiCad 10’s IPC Save Copy command, which can persist settings in the original project even when creating a copy.
Call run_drc with {"severity": "all"}. You can filter to "error" or "warning". A saved .kicad_pro is required so the check uses the project’s saved rules. The response includes a summary, up to 1,000 findings and the path to the complete JSON report; violations are returned as findings rather than a server failure. The check does not compare the PCB with its schematic. Filtered or excluded findings must not be interpreted as a complete clean-design result.
Call export_fabrication with these arguments for common manufacturing outputs:
{
"formats": ["gerbers", "drill", "positions"]
}These are also the defaults when formats is omitted. Gerbers, drill and position files share KiCad’s drill/place origin. Drill and position coordinates use millimetres; position export includes both sides and excludes DNP components. Gerber and SVG exports check zone fills and refill the private copy when necessary. "svg" exports a board drawing containing F.Cu, F.SilkS and Edge.Cuts. STEP export is not provided because a copied project can change how project-relative 3D model paths resolve. Export does not constitute a passing DRC check or manufacturing approval.
Results list generated files with paths and sizes on the machine running the MCP server. Outputs go into unique job directories under artifacts in the server’s state directory, or under KICAD_MCP_ARTIFACT_DIR when configured. Existing jobs are not overwritten. Temporary source copies are removed; successful reports and exports remain until you delete them. A remote MCP client may need a separate way to retrieve these local files.
Work with a bill of materials
The BOM is derived from the open PCB, including its current unsaved changes. It uses footprint values, library identifiers, custom fields and assembly flags available through KiCad’s PCB API. It does not read the schematic or resolve assembly variants.
get_bom and export_bom share these options:
Argument | Default | Behavior |
|
| Combine matching components into rows with references and a quantity per board; use |
|
| Include components marked “Do not populate” when enabled |
|
| Include components marked “Exclude from BOM” when enabled |
|
| Include all custom fields; provide a list to select particular custom fields |
Grouping compares values, complete library footprint identifiers and custom metadata, including manufacturer part numbers. Selecting fewer output fields does not merge components with different MPNs or other hidden metadata. References use natural ordering, such as R2 before R10. Quantities describe one copy of the board. Included components must have unique, annotated references; ambiguous or unannotated references produce an actionable error. Requested custom fields that are absent from a component are returned as empty strings.
A typical workflow is to inspect the BOM, update selected components, export it, and explicitly save the board if you want to keep the edits.
Call
get_bomwith these MCP arguments to inspect purchasing fields:
{
"grouped": true,
"include_dnp": false,
"include_excluded": false,
"fields": ["Manufacturer", "MPN"]
}Call
update_bom_fieldsto set the value, custom fields and assembly flags for selected references:
{
"references": ["R1", "R2"],
"value": "10k",
"fields": {
"Manufacturer": "Example Components",
"MPN": "EXAMPLE-10K-0603"
},
"dnp": false,
"exclude_from_bom": false
}Provide references and at least one change; omit options you do not want to change. Use value for the built-in component value and fields to add or edit custom metadata such as Manufacturer or MPN. The update uses a single undoable transaction and does not save the board. It is unavailable in read-only mode. Use an empty string to clear a custom field’s value. Reapplying identical values makes no changes and returns updated_count: 0.
Call
export_bomwith these arguments to retrieve CSV text:
{
"grouped": true,
"fields": ["Manufacturer", "MPN"],
"delimiter": ","
}The MCP response contains csv, a suggested filename, mime_type, row_count and component_count for your client to display or save. Choose comma (","), semicolon (";") or tab ("\t") as the delimiter. The server does not create a CSV file on disk. CSV quoting handles commas, newlines and Unicode; spreadsheet formula prefixes are escaped to prevent them from being evaluated as formulas. Custom column names that would collide with another CSV header are prefixed with Field:; the original names remain unchanged in get_bom.
Inspect the board and call
save_boardwith{}only when you want to save the result. This also saves any other pending PCB changes. You can undo the metadata update in KiCad before saving.
BOM updates modify PCB footprint data only. They do not edit or back-annotate the schematic. A later Update PCB from Schematic may overwrite these fields, so maintain the corresponding schematic metadata separately when it is the source of truth.
Install in KiCad
Requirements: KiCad 10.0 or later, Python 3.10+ with venv/pip support, and network access when dependencies are first installed. On Debian/Ubuntu, you may need the python3-venv package.
Using the Plugin and Content Manager
Download
hackinvent-kicad-mcp-0.3.1.zipfrom the releases page.In the KiCad project manager, open Plugin and Content Manager, choose Install from File and select the ZIP.
Enable the KiCad API in the plugin preferences, then open a PCB and reload the plugins or restart the editor.
Wait for the plugin’s Python environment to be created, then run Start MCP server.
The package is not yet listed in KiCad’s official plugin catalogue. Install it from the ZIP file.
From the repository
git clone https://github.com/HackInvent/kicad-mcp.git
cd kicad-mcp
python3 scripts/install_plugin.py --version 10.0The installer copies the plugin into KiCad’s user directory. It does not modify KiCad’s program files. Typical paths are:
Linux:
~/.local/share/KiCad/10.0/plugins/org.hackinvent.kicad-mcpmacOS:
~/Documents/KiCad/10.0/plugins/org.hackinvent.kicad-mcpWindows:
%USERPROFILE%\Documents\KiCad\10.0\plugins\org.hackinvent.kicad-mcp
Use --destination /exact/path/to/plugin to choose another location, for example when your Documents folder is redirected. To update this installation, add --overwrite; the installer first checks the existing plugin’s identifier. Avoid installing both the ZIP and a manual copy of the same plugin.
On Windows, use py or python instead of python3, depending on your installation.
Connect an MCP client over HTTP
After running Start MCP server, the server listens at this address by default:
http://127.0.0.1:8765/mcpA server-specific token protects every route. From the repository, retrieve the connection settings for running servers:
python3 scripts/connection_info.pyThis command uses only the Python standard library. It displays the url and token fields to provide to your client:
Transport : Streamable HTTP
URL : http://127.0.0.1:8765/mcp
Header : Authorization: Bearer <value of the token field>The configuration format depends on your client. It must support setting this HTTP header. Authentication uses a shared local token, without an OAuth server; clients that require OAuth cannot use this mode directly. Browser clients that send an Origin header are rejected; use a native MCP client or stdio mode.
The token changes on each startup unless KICAD_MCP_TOKEN is set. A fixed token must contain visible ASCII characters without whitespace; invalid values are rejected before the server starts. It is separate from KiCad’s internal IPC token. Do not include either token in issues or commits.
Without a copy of the repository, you can also find the connection settings in a session JSON file:
System | Session directory |
Linux |
|
macOS |
|
Windows |
|
These files contain a secret; POSIX permissions restrict access to their owner. Stop MCP server stops the server associated with the KiCad instance that launches the action. Session locks prevent concurrent startups for the same instance.
Stdio mode and development
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/kicad-mcp serve --transport stdioOn Windows, the environment’s executables are in .venv\Scripts\.
For a client that accepts the mcpServers format, adapt the paths in this example:
{
"mcpServers": {
"kicad": {
"command": "/ABSOLUTE/PATH/kicad-mcp/.venv/bin/python",
"args": ["-m", "kicad_mcp", "serve", "--transport", "stdio"]
}
}
}In this mode, the MCP client manages the server’s lifecycle; you do not need to click Start MCP server. The KiCad editor must remain open with its API enabled. With a single instance, kicad-python looks for the default KiCad socket. Use --socket or KICAD_API_SOCKET to target another instance. After restarting KiCad, restart the server to connect to the correct session.
Additional commands after installing the Python package:
kicad-mcp serve --transport streamable-http --port 8765
kicad-mcp serve --transport stdio --read-only
kicad-mcp status
kicad-mcp status --show-token
kicad-mcp stop--read-only exposes only the 15 inspection/BOM read tools and also blocks the other operations in the KiCad adapter. Selection, layer changes, DRC reports and fabrication exports are disabled because they change editor state or create files. export_bom remains available because it returns CSV text without creating a file. An already running server cannot change its read-only setting through a second start command: stop it first, then restart with the intended setting. status hides the token by default. When multiple servers are running, use stop --socket /path/to/socket to select the instance to stop.
Configure startup from KiCad
Set these variables before starting KiCad:
Variable | Effect |
| HTTP port, |
| Optional fixed HTTP token to keep the client configuration unchanged |
| Enable read-only mode |
| Override the session directory |
| Full path to kicad-cli for DRC and fabrication tools; otherwise search PATH |
| Override the directory that stores DRC reports and manufacturing exports |
KiCad automatically passes KICAD_API_SOCKET and KICAD_API_TOKEN to plugin actions. For multiple simultaneous instances, use different ports or KICAD_MCP_PORT=0, then retrieve their URLs with connection_info.py.
Verification
.venv/bin/ruff check .
.venv/bin/python -m pytest -q
.venv/bin/python -m build
python3 scripts/build_plugin.pyCI runs these checks on Python 3.10, 3.12 and 3.13. Tests cover real HTTP/stdio MCP clients, errors, access restrictions, repeated startups, shutdown, KiCad units, transaction rollback, BOM grouping and CSV export, metadata updates, pad/via/zone inspection, stackup, selection and deletion, DRC/export command handling, artifact cleanup, and PCM archives. The tests use simulated editor and CLI boundaries; they do not require a KiCad GUI or kicad-cli.
For a manual check on a copy of a test PCB:
Install the plugin and start the server from KiCad.
Connect a client and call
kicad_status,get_board_infoandlist_footprints.Move an unlocked component and check its coordinates, then undo the change in KiCad.
Add text and a track on enabled layers; inspect the result and run DRC in the editor.
Read a BOM, update Manufacturer/MPN on test components, export the CSV and verify grouping, quantities and DNP filtering. Undo the metadata update in KiCad.
Inspect pads, zones, stackup and a net; select an item by UUID and check layer visibility.
Create and delete a test via, verify undo behavior, then request zone refill and wait for KiCad to finish.
Call
save_boardonly if the result is as expected. Runrun_drc, compare the report with the editor’s DRC, and check Gerbers, drill files and positions in appropriate viewers before manufacturing.Stop the server using the KiCad action and confirm that the client disconnects.
If the plugin does not appear, check the Python environment and KiCad’s messages. If the server cannot connect, check that the API is enabled, a PCB is open and the correct socket is selected. If the port is occupied, choose another KICAD_MCP_PORT.
Architecture and references
flowchart LR
A[MCP client] -->|Local Streamable HTTP or stdio| B[Python MCP server]
B --> C[KiCad adapter with serialized access]
C -->|IPC Protobuf / NNG| D[KiCad PCB editor]
P[KiCad plugin action] -->|Start / stop| B
C -->|Copy saved PCB and project context| S[Private job directory]
S --> K[kicad-cli DRC and exports]
K --> F[Local reports and manufacturing files]src/kicad_mcp/server.py: MCP tools and HTTP authentication.src/kicad_mcp/bridge.py: IPC access, conversions and edit transactions.src/kicad_mcp/inspection.py: pads, vias, zones, item details, nets and stackup.src/kicad_mcp/editing.py: selection, layer controls, vias, deletion and zone refill.src/kicad_mcp/fabrication.py: saved-board snapshots, kicad-cli and artifact management.src/kicad_mcp/bom.py: BOM grouping, CSV generation and metadata validation.src/kicad_mcp/__main__.py: transports, sessions and control commands.plugin/: IPC manifest, dependencies and KiCad actions.scripts/: local installation, connection settings and PCM packaging.
Official references: KiCad IPC API, kicad-python library, KiCad 10 CLI, KiCad package format, MCP Python SDK, 1.x branch.
See CHANGELOG.md for release history.
MIT license.
Available Tools
13 toolsadd_textADestructive
Add PCB text at absolute mm coordinates on the specified layer; do not save.
Inputs: text (required), x_mm (required), y_mm (required), layer, +1 more. Returns: object
add_trackADestructive
Add one straight copper track, optionally assigned to an existing net; no autorouting or DRC.
Inputs: end_x_mm (required), end_y_mm (required), start_x_mm (required), start_y_mm (required), +3 more. Returns: object
export_bomBRead-onlyIdempotent
Return a spreadsheet-safe CSV BOM as text, without writing a file; delimiter may be comma, semicolon or tab.
Inputs: fields, grouped, delimiter, include_dnp, +1 more. Returns: object
get_board_infoARead-onlyIdempotent
Read the active PCB's name, layers and item counts.
Inputs: no named parameters. Returns: object
get_bomARead-onlyIdempotent
Read the PCB bill of materials with quantities and custom fields; omit DNP/excluded parts by default.
Inputs: fields, grouped, include_dnp, include_excluded. Returns: object
get_selectionARead-onlyIdempotent
Read the items currently selected in the PCB editor.
Inputs: no named parameters. Returns: object
kicad_statusARead-onlyIdempotent
Check the connection to KiCad and report the editor version.
Inputs: no named parameters. Returns: object
list_footprintsARead-onlyIdempotent
List components, references, values and placement in mm; optionally filter by reference.
Inputs: reference. Returns: object
list_netsARead-onlyIdempotent
List the electrical nets of the active PCB.
Inputs: no named parameters. Returns: object
list_tracksARead-onlyIdempotent
Read PCB tracks, widths, positions, copper layers and nets.
Inputs: no named parameters. Returns: object
move_footprintADestructive
Move one unlocked component to absolute mm coordinates, with optional rotation; do not save.
Inputs: x_mm (required), y_mm (required), reference (required), rotation_degrees. Returns: object
save_boardADestructiveIdempotent
Explicitly save the active PCB, including unsaved changes made in the editor, to its current file.
Inputs: no named parameters. Returns: object
update_bom_fieldsADestructive
Update custom BOM fields, value or assembly flags on exact PCB references in one undo step; do not save or change the schematic.
Inputs: references (required), dnp, value, fields, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool has a distinct purpose: listing nets vs. tracks vs. footprints, reading vs. writing board info, and save/status are clearly separated. No overlapping or ambiguous tool boundaries.
Most tools follow a clear verb_noun pattern (list_*, get_*, update_*, add_*, save_*, export_*), with a few exceptions like 'kicad_status' and 'get_board_info' breaking the strict verb-first pattern. Overall naming is predictable and readable.
13 tools is a reasonable, focused set for a KiCad PCB MCP server. Each tool covers a necessary operation without redundancy, and the count is within the ideal 3-15 range.
The set covers core PCB inspection, modification, and board management operations. Minor gaps exist such as no explicit tool for deleting objects or modifying tracks/footprints, but the surface is largely complete for typical read/modify workflows.
Maintenance
Related MCP Connectors
EasyGerber brings AI printed circuit board (PCB) design, layout, and routing to MCP-compatible assistants. Describe a circuit or start from firmware pin assignments, search published electronic components, and build schematics using catalog parts with their footprints and available 3D models. Create and revise boards, generate layouts with automatic component placement and routing, inspect previews, and check saved layouts for blocking design issues. Export manufacturing ZIPs containing Gerber and drill files, a bill of materials, and component placement data, or download an editable EasyGerber (.egb) file. Start without signing up. Your agent uses one private board reference to create and continue a board, including catalog access, edits, layout, checks, previews, and exports, without a separate guest setup step or token to manage. To keep the board in your account or work with permitted saved personal or organization boards, complete EasyGerber sign-in and OAuth consent, then resume the same task. Account permissions, plan limits, and generation billing apply; support depends on your MCP client and installed integration.
Design, route, check, review and export manufacturable PCBs from plain language; KiCad import.
Design and revise PCBs from plain language, track jobs, and retrieve design artifacts.
Read and edit the Revit 2024–2027 model on your PC. Needs the free Revit MCP add-in.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that exposes KiCad PCB design automation tools to AI assistants and other MCP clients.-
- AlicenseAqualityDmaintenanceEnables AI assistants to read and modify KiCAD PCB designs through the KiCAD IPC API, providing tools for board queries, footprint placement, track creation, DRC, and export.14MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server for controlling KiCad EDA software, enabling schematics, PCB design, manufacturing outputs, design checks, and library management through any MCP-compatible AI assistant.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for KiCad 10 that enables AI assistants to inspect and control schematics and PCB layouts in real-time using the official kipy Python bindings.109 PyPI1MIT