Skip to main content
Glama

librepcb-mcp

A Model Context Protocol server that lets AI agents such as Claude Code inspect, edit, check and export real LibrePCB projects on Linux. It runs natively (no Wine, Docker, browser or HTTP service) over STDIO.

  • Reads LibrePCB's native project files with a parser that reproduces LibrePCB's canonical S-expression output byte for byte.

  • Edits mirror what the LibrePCB editor writes. Every edit is backed up, written atomically, then re-opened with librepcb-cli open-project --strict. If LibrePCB rejects it, the edit is rolled back and the CLI output comes back as the error.

  • ERC, DRC and all exports are run by librepcb-cli, never emulated.

Design notes and research results: docs/architecture.md.

Requirements

LibrePCB

2.x (project file format 2). Tested with 2.1.1 (Flatpak). Older projects must be upgraded first: librepcb-cli open-project --save project.lpp

Python

3.12+ (tested 3.14)

Linux

any distribution with the above; tested on Void Linux (x86_64). Uses librepcb-cli from PATH (distro package, AppImage, official tarball) or the Flatpak org.librepcb.LibrePCB.

Python packages

mcp>=2.3,<3 (official SDK, MCPServer API)

Related MCP server: dcc-mcp-kicad

Feature status

Group

Tools

Status

Project

create_project, list_projects, get_project_info, validate_project, backup_project, server_status

working

Schematic inspection

list_schematics, list_components, get_component, list_nets, get_net_connections, inspect_schematic

working

Schematic editing

create_schematic, add_component, remove_component, move_component, set_component_value, connect_pins, disconnect_pins, create_net, add_net_label

working

Board

list_boards, get_board_info, create_board, add_device_to_board, place_component, rotate_component, set_board_outline, create_trace, create_via

working

Routing

route_net

straight-line only: shortest spanning tree, no obstacle avoidance. Not an autorouter.

Validation

run_erc, run_drc

working (librepcb-cli)

Export

export_schematic_pdf, export_board_pdf, export_gerbers (Gerber and Excellon drills), export_bom, export_project (.lppz), run_output_jobs

working (librepcb-cli)

Library

list_libraries, search_components, get_component_details, get_device_details, list_footprints

working

Intentionally not provided: open_project / save_project (the server is stateless; each edit is saved and verified immediately), a separate export_drill_files (drills come with export_gerbers), and get_validation_results (call run_erc / run_drc / validate_project, which return the results).

Not implemented: copper planes/zones, net renaming/merging, buses, schematic polygons/texts, mirrored schematic symbols, design-rule editing, creating library elements, autorouting. See docs/architecture.md.

Installation

git clone https://github.com/arcbaseproject/librepcb-mcp.git
cd librepcb-mcp
python3 -m venv .venv
.venv/bin/pip install -e .          # or: .venv/bin/pip install -e '.[dev]' for tests

LibrePCB CLI

Install LibrePCB 2.x by any official route, e.g.

flatpak install --user flathub org.librepcb.LibrePCB      # Flatpak
# or a distro package / the official tarball/AppImage providing `librepcb-cli`

Detection order: $LIBREPCB_CLI → librepcb-cli on PATH → the Flatpak. Check with the server_status tool or:

LIBREPCB_MCP_ROOTS=$HOME .venv/bin/python -c "from librepcb_mcp.config import Config; print(Config.from_env().cli)"

Flatpak note: the Flatpak sandbox only sees your home directory, so keep projects (and export directories) under $HOME.

Libraries

search_components / add_component need installed LibrePCB libraries. Either install them in LibrePCB (Library Manager; the workspace is auto-detected from LibrePCB's config or ~/LibrePCB-Workspace), or point the server at *.lplib directories:

git clone --depth 1 https://github.com/LibrePCB-Libraries/LibrePCB_Base.lplib ~/librepcb-libs/LibrePCB_Base.lplib
export LIBREPCB_MCP_LIBRARIES=~/librepcb-libs

Configuration (environment variables)

Variable

Meaning

LIBREPCB_MCP_ROOTS

Required. :-separated directories the server may read and modify. Everything else is refused (symlinks are resolved first).

LIBREPCB_MCP_LIBRARIES

:-separated *.lplib dirs or dirs containing them. Default: LibrePCB workspace libraries.

LIBREPCB_CLI

CLI command, e.g. /usr/bin/librepcb-cli or flatpak run --command=librepcb-cli org.librepcb.LibrePCB.

LIBREPCB_MCP_BACKUP_DIR

Backup location. Default $XDG_STATE_HOME/librepcb-mcp/backups (last 20 per project).

LIBREPCB_MCP_CLI_TIMEOUT

Seconds per CLI call, default 300.

LIBREPCB_MCP_LOG

Log level for stderr, default WARNING.

Claude Code integration

Verified with Claude Code 2.1.330 (claude mcp list reports ✔ Connected, and a headless claude -p session called get_project_info on the example project):

claude mcp add librepcb --transport stdio \
  -e LIBREPCB_MCP_ROOTS=$HOME/pcb-projects \
  -e LIBREPCB_MCP_LIBRARIES=$HOME/librepcb-libs \
  -- /absolute/path/to/librepcb-mcp/.venv/bin/python -m librepcb_mcp

Put the server name before -e (-e accepts several values and would otherwise swallow the name). Add -s user to make it available in every directory. Check with claude mcp get librepcb.

Other MCP clients: run /absolute/path/.venv/bin/python -m librepcb_mcp (or the installed librepcb-mcp script) as a STDIO server with the environment variables above.

Conventions

  • Units: millimeters and degrees (counter-clockwise). LibrePCB's y axis points up. Schematic grid is 2.54 mm.

  • Components: designator (R1) or UUID. Pins: DESIGNATOR:PIN, PIN = symbol pin name or signal name (R1:1, LED1:A, U1:VCC). Board pads: DESIGNATOR:PAD; vias: via:<uuid>.

  • Schematics/boards: name, UUID or index; default is the first.

  • Edit results include success, the changed files, the backup path and what verified the result. Errors come back as MCP tool errors with LibrePCB's own message where relevant.

  • Close the project in the LibrePCB GUI before editing: the server refuses to write while LibrePCB's .lock file exists.

Tool reference

Tool

Purpose

server_status

Roots, CLI command/version, libraries, backup dir

create_project

New project with schematic Main and optional board (outline size in mm)

list_projects

Find *.lpp below the roots

get_project_info

Metadata, schematics, boards, counts, lock state

validate_project

Strict open + ERC + DRC

backup_project

Manual backup

list_schematics / inspect_schematic

Pages; symbols and every wire/label per net segment

list_components / get_component

Components; details with pin and pad positions and nets

list_nets / get_net_connections

Nets with connected signals, labels, traces, vias

create_schematic

Add a page

add_component

Add a library device's component; places all gates

remove_component

Delete with attached wires/traces; drop unused nets

move_component

Move/rotate a schematic symbol

set_component_value

Value text and attribute values (e.g. RESISTANCE)

connect_pins

Wire two pins on one page into one net (named or auto)

disconnect_pins

Remove wires from pins, detach from net and traces

create_net

Named net

add_net_label

Stub wire + net label: connect by net name (GND, VCC), across pages

list_boards / get_board_info

Boards; outline, devices, unplaced parts, per-net unrouted count

create_board

Additional board

add_device_to_board

Place a component's footprint (optionally bottom side)

place_component / rotate_component

Move, rotate, flip devices

set_board_outline

Polygon or rectangle outline

create_trace

Trace between pads/vias of one net, optional corner points

create_via

Through via on a net

route_net

Straight traces joining all unconnected pads of a net

run_erc / run_drc

LibrePCB's checks; non-approved messages with severity

export_schematic_pdf, export_board_pdf, export_gerbers, export_bom, export_project

Exports into <project>/output/mcp (or output_dir)

run_output_jobs

Run the project's own output jobs

list_libraries, search_components, get_component_details, get_device_details, list_footprints

Library browsing

Example

examples/led-circuit/ is a 5 V LED circuit (test pads for +5V/GND, 330 Ω 0603 resistor, red 3 mm THT LED) on a 30 × 20 mm board. It was generated entirely through this server's MCP tools, opens in LibrePCB 2.1.1 in strict mode, and passes ERC and DRC with zero messages. Prompts that work with Claude Code:

  • "Show me the components and nets of examples/led-circuit."

  • "Change R1 to 470 Ω, run ERC and DRC, then export Gerbers."

  • "Create a new project in ~/pcb-projects/blinky with a resistor and a green LED in series between VCC and GND, place them on a 25×15 mm board and route it."

A typical tool sequence: search_components → create_project → add_component → connect_pins / add_net_label → run_erc → add_device_to_board → get_board_info → create_trace / route_net → run_drc → export_gerbers.

Passing ERC and DRC does not mean a design is electrically correct, safe, or ready to manufacture. Review designs in LibrePCB before ordering boards.

Troubleshooting

Symptom

Fix

No project directories configured

Set LIBREPCB_MCP_ROOTS

outside the configured project roots

Add the directory to LIBREPCB_MCP_ROOTS

librepcb-cli not found

Install LibrePCB 2.x or set LIBREPCB_CLI; edits are refused without it

CLI cannot open files (Flatpak)

Keep projects and outputs under $HOME

Project is open in LibrePCB

Close it in LibrePCB, or delete a stale .lock after a crash

Unsupported project file format

librepcb-cli open-project --save project.lpp (makes a format-2 copy in place; back up first)

No libraries found

Install libraries in LibrePCB or set LIBREPCB_MCP_LIBRARIES

LibrePCB rejected the modified project

Nothing was changed; the message contains LibrePCB's reason. Please report it as a bug with that output.

Nothing in Claude Code

claude mcp get librepcb; run the command manually; set LIBREPCB_MCP_LOG=DEBUG (logs go to stderr)

Limitations

  • route_net draws straight lines; DRC violations are expected on dense boards.

  • No planes/zones, no net renaming or merging, no buses, no schematic graphics.

  • Schematic symbols are placed unmirrored; boards: top or bottom side.

  • add_component uses the component's first symbol variant and, on boards, the first footprint unless one is named.

  • Components are added with an assembly option for the chosen device but no MPN/part.

  • .lppz archives are not edited.

  • Read results are computed from the files; DRC/ERC results come from LibrePCB only.

Development

.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest                 # unit, integration, MCP protocol tests
.venv/bin/pip install ruff && .venv/bin/ruff check src tests

Tests that need librepcb-cli or LibrePCB_Base.lplib are skipped with a reason when they are missing (LIBREPCB_CLI, LIBREPCB_MCP_TEST_LIBRARY select them). Work directories are created under ~/.cache/librepcb-mcp-tests so the Flatpak CLI can read them.

Last run (2026-11-20, LibrePCB 2.1.1 Flatpak, Python 3.14, mcp 2.3.0): 49 passed, 0 skipped.

License

GPL-3.0-or-later (see LICENSE). The example project embeds elements from LibrePCB_Base.lplib (CC0-1.0) and LibrePCB's newstroke.bene font.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      C
      maintenance
      Enables AI agents to create and edit real KiCad schematics and projects, run ERC/DRC validation, generate BOMs, and produce schematic/PCB/3D renders via kicad-cli, with SKiDL support and automatic backups.
      28
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables trusted local AI agents to create, inspect, edit, save, reopen, and export isolated headless KiCad 9 PCB board files, including native design-rule-check reports, through typed MCP tools. Operations are bounded to native pcbnew and kicad-cli calls within a single explicit trusted workspace, with no arbitrary script execution, live PCB Editor control, or IPC access.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Lets AI agents read, review, and edit PCB designs in Autodesk Fusion Electronics, covering schematic capture, placement, impedance-controlled routing, pours and stitching, design checks, and JLCPCB manufacturing outputs. Every change is verified by reading the design back from Fusion and rolled back if it does not match, with each tool call acting as a single undo step until the user saves.
      77
      9
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables an AI agent to do end-to-end PCB design work — component sourcing, schematic construction, placement, routing, SPICE simulation and manufacturing export — by driving KiCad through its project files and kicad-cli, with no running GUI required. Boards are only reported as routed or done when a machine-checked verification gate returns an unambiguous PASS, so unverified or partially checked results are never presented as finished.
      19
      MIT