librepcb-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
Python | 3.12+ (tested 3.14) |
Linux | any distribution with the above; tested on Void Linux (x86_64). Uses |
Python packages |
|
Related MCP server: dcc-mcp-kicad
Feature status
Group | Tools | Status |
Project |
| working |
Schematic inspection |
| working |
Schematic editing |
| working |
Board |
| working |
Routing |
| straight-line only: shortest spanning tree, no obstacle avoidance. Not an autorouter. |
Validation |
| working (librepcb-cli) |
Export |
| working (librepcb-cli) |
Library |
| 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 testsLibrePCB 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-libsConfiguration (environment variables)
Variable | Meaning |
| Required. |
|
|
| CLI command, e.g. |
| Backup location. Default |
| Seconds per CLI call, default 300. |
| Log level for stderr, default |
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_mcpPut 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
.lockfile exists.
Tool reference
Tool | Purpose |
| Roots, CLI command/version, libraries, backup dir |
| New project with schematic |
| Find |
| Metadata, schematics, boards, counts, lock state |
| Strict open + ERC + DRC |
| Manual backup |
| Pages; symbols and every wire/label per net segment |
| Components; details with pin and pad positions and nets |
| Nets with connected signals, labels, traces, vias |
| Add a page |
| Add a library device's component; places all gates |
| Delete with attached wires/traces; drop unused nets |
| Move/rotate a schematic symbol |
| Value text and attribute values (e.g. |
| Wire two pins on one page into one net (named or auto) |
| Remove wires from pins, detach from net and traces |
| Named net |
| Stub wire + net label: connect by net name (GND, VCC), across pages |
| Boards; outline, devices, unplaced parts, per-net unrouted count |
| Additional board |
| Place a component's footprint (optionally bottom side) |
| Move, rotate, flip devices |
| Polygon or rectangle outline |
| Trace between pads/vias of one net, optional corner points |
| Through via on a net |
| Straight traces joining all unconnected pads of a net |
| LibrePCB's checks; non-approved messages with severity |
| Exports into |
| Run the project's own output jobs |
| 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 |
| Set |
| Add the directory to |
| Install LibrePCB 2.x or set |
CLI cannot open files (Flatpak) | Keep projects and outputs under |
| Close it in LibrePCB, or delete a stale |
|
|
| Install libraries in LibrePCB or set |
| Nothing was changed; the message contains LibrePCB's reason. Please report it as a bug with that output. |
Nothing in Claude Code |
|
Limitations
route_netdraws 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_componentuses 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.
.lppzarchives 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 testsTests 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Design, route, check, review and export manufacturable PCBs from plain language; KiCad import.
Design circuits, simulate and verify embedded firmware, and lay out PCBs with AI agents.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Turn datasheets into source-backed JSON contracts, pinout matrices, and KiCad CAD for AI agents.
Related MCP Servers
- FlicenseBqualityCmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseBqualityBmaintenanceLets 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.779MIT
- AlicenseAqualityBmaintenanceEnables 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.19MIT