# agentee MCP server

> agentee mcp serves a project over the Model Context Protocol on stdio: 30 tools to check, render, route, simulate and write the fab package, with setup for Claude Code, Codex, Cursor and other MCP clients.

```json
{ "mcpServers": { "agentee": { "command": "agentee", "args": ["mcp", "/path/to/project"] } } }
```

```sh
claude mcp add agentee -- agentee mcp /path/to/project
```

## Tools

### format_reference

The file format reference for boards, symbols and footprints, with examples. Read this before writing files.

No arguments.

### check

Load the project and report errors and warnings for every item, or one item.

- `include_info` (boolean): also list info notes
- `item` (string): only this board, symbol or footprint

### drc

Design rule checks of a layout. With list = true: every DRC rule with its id, category, severity, and whether it applies to this board and why. Without: the layout's diagnostics that carry a rule id. Rule ids go in the board's [drc] disable list or severity table.

- `list` (boolean)
- `name` (string, required): layout or board

### layout

Run the layout engine on a layout: the configured [engine] phases in order, then the score per term with the worst offenders of each. Phases not implemented yet are listed as skipped.

- `dry_run` (boolean): report without writing the plan
- `from` (string): start at this phase
- `name` (string, required)
- `only` (string): run one phase
- `to` (string): stop after this phase

### stackups

Stackup presets for a board's `stackup.preset`: JLCPCB and PCBWay builds and generic HDI builds with layer thicknesses and er. Filter the list, or give name to get one preset's layers.

- `fab` (string): jlcpcb, pcbway or generic
- `layers` (integer): copper layer count
- `name` (string): one preset, returns its layers
- `search` (string): substring of name or description
- `thickness` (number): finished thickness in mm, within 10%

### list_items

Every board, symbol and footprint in the project with its file and error counts.

No arguments.

### show_item

The resolved model of one item as JSON: pins with positions, expanded pad arrays, stackup with computed trace geometry, impedance and current analysis.

- `name` (string, required)

### render_item

Render an item to PNG exactly as the viewer shows it and return the image.

- `canvas_only` (boolean): drop the side panels
- `height` (integer)
- `hidden_pins` (boolean)
- `hide` (array)
- `name` (string, required)
- `region` (array): zoom to [x0, y0, x1, y1] in mm
- `save_to` (string): also write the PNG here, relative to the project
- `show` (array): layers to turn on, e.g. F.Fab, F.Mask, In1.Cu
- `unit` (integer): symbol unit, 1 based
- `width` (integer)

### kicad_search

Search the installed KiCad libraries by name. Every word must match Library:Name.

- `kind` (string, required)
- `limit` (integer)
- `query` (string, required)

### import_kicad_symbol

Convert a KiCad symbol (Library:Name) into a .sym.toml in the project. with_footprint also imports its default footprint, or give footprint to pick one.

- `dir` (string): relative to the project, default symbols/
- `footprint` (string): Library:Name of the footprint to import and link
- `force` (boolean)
- `spec` (string, required): Library:Name, e.g. Amplifier_Operational:LM358
- `with_footprint` (boolean)

### import_kicad_footprint

Convert a KiCad footprint (Library:Name) into a .fp.toml in the project.

- `dir` (string): relative to the project, default footprints/
- `force` (boolean)
- `spec` (string, required): Library:Name, e.g. Package_SO:SOIC-8_3.9x4.9mm_P1.27mm

### new_item

Write a starter file for a board, symbol, footprint, schematic, layout or sim, to edit from. A sim starts as an FDTD run of a layout, or with sim_kind logic as a logic sim of a schematic (clock, reset, a clocked assertion) whose nets you rename.

- `dir` (string): relative to the project
- `kind` (string, required)
- `name` (string, required)
- `sim_kind` (string): with kind sim, default fdtd

### trace_width

Minimum track width for a current (IPC-2221).

- `copper` (string)
- `current` (string, required): e.g. 2A or 500mA
- `internal` (boolean)
- `temp_rise` (string)

### run_sim

Run a simulation (*.sim.toml): an FDTD run of a layout on the GPU (ports on pads, lumped models for passives, S-parameters saved as JSON and Touchstone next to the spec), any other kind (dc, thermal, cascade, channel, pdn), or a logic sim of the schematic netlist (stimulus, assertions, setup and hold, a VCD next to the spec). Render the sim afterwards to see the plot or the waveforms.

- `name` (string, required)

### serpentine

Points for a track that replaces a straight segment and adds a given length as trombone bumps to one side. Paste them into the track's points.

- `add` (string, required): e.g. 2.5mm
- `amplitude` (string)
- `from` (string, required): x,y in mm
- `pitch` (string)
- `to` (string, required): x,y in mm

### tie

Tie every SMD pad of a plane net (a net with a [[zones]] entry) to the nearest plane layer with a short stub and a via beside the pad, away from the part body, and append them to the layout file. Use this for ground and supply pads instead of routing tracks between them; `route` with a glob skips plane nets.

- `dry_run` (boolean)
- `name` (string, required)
- `nets` (string): comma separated plane nets, globs allowed, default every net with a zone

### route

Autoroute the ratsnest of the named nets of a layout on a grid, keeping each class's width, clearance, layers and via, and append the tracks and vias to the layout file. Existing copper is never moved unless reroute is set.

- `bend_cost` (number): mm of track per 45 degree bend, three times that for 90
- `dry_run` (boolean)
- `grid` (number)
- `layers` (string): comma separated copper layers, default all
- `name` (string, required)
- `nets` (string, required): comma separated, * and ? globs
- `pairs` (boolean)
- `reroute` (boolean): remove these nets' tracks and vias first
- `via` (string): comma separated [[vias]] names from the board to choose from, default the class vias
- `via_cost` (number)
- `via_in_pad` (boolean): allow vias fully inside SMD pads (filled and capped); by default vias keep off every SMD pad

### fill

Fill the zones of a layout and store the copper at the end of its file, so loads and the viewer skip the fill until the zone's copper, clearances or neighbours change.

- `name` (string, required)

### tune

Length-match a layout: meander the short net of every pair over its skew limit and every match group member short of its target, on the longest segments where the bumps clear every other net, and write the points back into the tracks.

- `amplitude` (number): largest bump height in mm
- `dry_run` (boolean)
- `name` (string, required)
- `nets` (string): comma separated globs, default all
- `pitch` (number): bump pitch in mm

### neck

Neck down track ends that enter a pad narrower than the track or break clearance near the pad: the end becomes a separate [[tracks]] entry with an explicit width, the smallest of the class width, the pad's smaller side and the widest that keeps clearance, rounded down to 0.01 mm, never under min_track_width and never longer than the class neckdown. taper steps the width down over a short chain of segments. Stored zone fills are refreshed.

- `dry_run` (boolean)
- `name` (string, required)
- `nets` (string): comma separated globs, default all
- `taper` (boolean)

### place

Place the layout's parts automatically as a quick start: connectors and edge-mount parts on the board edges (never an RF and a USB connector on one edge unless it must), mounting holes and fiducials in the corners, the largest chips near the centre, each IC's decoupling caps, crystal and pull-ups clustered at the pins they serve, placed by weighted wirelength, then legalised on a 0.05 mm grid with no courtyard overlaps and refined by simulated annealing. Writes at, rotation and side into [[footprints]] and refreshes the stored fills. Parts with locked = true stay put.

- `dry_run` (boolean)
- `keep_placed` (boolean): leave every part that already has a placement
- `name` (string, required)
- `parts` (string): comma separated globs of the parts to place, default all
- `seed` (integer): default 1; the same seed gives the same placement
- `side` (string): F, B or both, default F

### silk

Move every silk reference that check flags to the clear spot it suggests, repeating until the labels settle, and optionally hide the ones that have nowhere to go. Writes label = { at, rotation } or hide = true into the footprints.

- `dry_run` (boolean)
- `hide` (boolean)
- `name` (string, required)

### testpoints

Add a test pad to each net that needs probe access and has none: a TestPoint part (TestPoint_Pad_D1.0mm footprint, both written into the project if missing) joined to the net in the schematic sheet that lists it, a footprint on the probe side in free space near the net's copper, and an autorouted track and via from the net's copper. Nets default to the layout's [test] nets; impedance and pair nets are skipped.

- `dry_run` (boolean)
- `name` (string, required)
- `nets` (string): comma separated, * and ? globs, any case; default the [test] nets
- `pitch` (number): grid and least spacing of the test pads, mm
- `side` (string): probe side F or B, default the [test] side (B)

### sparam

Analyse a finished sim or cascade: passivity and reciprocity, a TDR of one port (impedance against time with a Gaussian edge), mixed-mode Sdd/Scc/Scd for a pair given as IN+,IN-,OUT+,OUT-, and crosstalk FROM,TO in frequency and as a step.

- `name` (string, required)
- `pair` (string)
- `rise` (string): 10-90% rise, e.g. 35ps
- `tdr` (string): port name or number
- `xtalk` (string)

### models

Find the 3D models (STEP or VRML) the project's footprints name, downloading missing KiCad library models into the cache. Reports each model's path and triangle count, or why it is missing.

No arguments.

### fab

Write the fab package for a layout into a folder: RS-274X Gerbers (X2) per copper, mask, paste, silk and edge layer, Excellon drills, a zip of those for upload, BOM (generic and JLCPCB), pick-and-place, fab notes and assembly drawings. Refuses while the layout has errors.

- `name` (string, required)
- `out` (string, required): output folder, relative to the project

### export

Write a layout as one STEP assembly for enclosure CAD: the board as a solid with its drilled holes and cutouts, each part's STEP model embedded and placed, and VRML, generated and missing models as surfaces or boxes. Board bottom at z = 0, X and Y as the layout with Y up.

- `name` (string, required)
- `out` (string, required): output .step file, relative to the project

### parts

Price a layout's or schematic's BOM at Mouser and Farnell and find cheaper equivalents: the same part at the other distributor, resistors and ceramic capacitors with the same value, package, tolerance, voltage and dielectric (never a downgrade), generic discretes (2N7002, S1D, SS14, SMAJ..) by name and package, indicator LEDs by colour and package, and the distributor's suggested replacement for parts going obsolete. Costs are at the needed quantity, buying up to a price break when that is cheaper. Keys come from ~/.config/agentee/distributors.toml ([mouser] api_key, [farnell] api_key and store).

- `alternatives` (boolean)
- `boards` (integer)
- `distributors` (array): mouser, farnell; default every one with a key
- `farnell_store` (string): e.g. uk.farnell.com, ie.farnell.com, www.newark.com
- `name` (string, required): layout or schematic
- `refs` (array): only the BOM lines holding these references

### field_solve

Solve a trace cross-section with the GPU field solver: impedance, effective permittivity, C and L per metre, delay. Includes solder mask, thickness, coplanar grounds and differential pairs. Within 0.5% of exact references with fine = true.

- `board` (string)
- `coplanar_gap` (string)
- `fine` (boolean)
- `gap` (string): differential pair gap
- `layer` (string)
- `netclass` (string): take width and gaps from this class
- `no_mask` (boolean)
- `sweep` (string): loss sweep START,STOP,POINTS, e.g. 10MHz,20GHz,21: R, L, G, C, Z0 and dB/in per frequency with skin effect, stackup roughness and a causal (Djordjevic-Sarkar) dielectric
- `width` (string)

### impedance

Trace impedance on a board layer for a width (and pair gap), or the width that hits a target.

- `board` (string): board name, optional when there is one
- `coplanar_gap` (string): gap to the ground pour either side, grounded coplanar on outer layers
- `gap` (string): differential pair gap
- `layer` (string)
- `target` (string): e.g. 50ohm
- `width` (string)