Skip to main content
Glama
rjmendez

mcp-server-kicad-tools

by rjmendez
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

kicad-mcp-tools

CI License: MIT PyPI

Standalone KiCad automation toolkit extracted from the MycoMIDI project.

What is this?

kicad-mcp-tools is a small, stdlib-only Python toolkit for automating common KiCad-adjacent tasks without depending on a running KiCad instance. It packages reusable helpers that started life inside MycoMIDI and proved useful enough to stand alone.

It currently includes:

  • kicad_mcp_tools.sexpr_cst — lossless KiCad S-expression CST parser and serializer

  • kicad_mcp_tools.atomic_write — same-directory atomic file replacement helper

  • kicad_mcp_tools.drc_classify — DRC/ERC JSON classifier for clean/findings/malformed states

  • kicad_mcp_tools.pin_header_footprint_gen — simple through-hole pin-header footprint generator

  • scripts/kicad-cli.sh — pinned Docker wrapper for kicad-cli

  • demo/ — tiny sample schematic and PCB inputs for CLI experiments

Related MCP server: mcp-kicad-cli

Why does it exist?

This repository was split out from the hardware-design automation work behind MycoMIDI, a bioelectric-signal-to-MIDI project that needed lightweight, scriptable KiCad tooling during schematic, PCB, and validation workflows.

The extraction keeps that tooling reusable for other projects while preserving credit to the open-source KiCad MCP server work that informed the approach:

Origin and attribution

These files were extracted from MycoMIDI without removing MycoMIDI's own copy. The implementation and attribution headers were preserved from that origin.

The toolkit also preserves attribution to the upstream MIT-licensed projects whose patterns were adapted in MycoMIDI:

See THIRD_PARTY_LICENSES.md for the preserved third-party license text and provenance notes.

Installation

Once the package is published:

pip install kicad-mcp-tools

From source today:

git clone https://github.com/rjmendez/kicad-mcp-tools.git
cd kicad-mcp-tools
pip install -e .

Using as an MCP server

Run the stdio server directly from the published package with uvx:

uvx --from kicad-mcp-tools mcp-server-kicad-tools

Example MCP client configuration:

{
  "mcpServers": {
    "kicad-tools": {
      "command": "uvx",
      "args": ["--from", "kicad-mcp-tools", "mcp-server-kicad-tools"]
    }
  }
}

Exposed tools:

  • parse_kicad_sexpr — parse KiCad S-expression text into a structured CST-like tree.

  • roundtrip_kicad_sexpr — re-serialize parsed KiCad S-expression text and report whether it round-trips exactly.

  • classify_drc_report — classify KiCad DRC/ERC JSON as clean, findings, malformed, or unavailable.

  • generate_pin_header_footprint — generate a KiCad .kicad_mod pin-header footprint S-expression.

Run tests

python3 -m unittest discover tests

Quickstart

from kicad_mcp_tools import generate_electrode_connector_footprint, parse

footprint = generate_electrode_connector_footprint(4)
tree = parse(footprint.encode("utf-8"))

print(tree.lists[0].head)          # footprint
print(len(tree.lists[0].find_all("pad")))  # 4

Available Tools

4 tools
classify_drc_reportB

Classify KiCad DRC/ERC JSON as clean, findings, malformed, or unavailable.

ParametersJSON Schema
NameRequiredDescriptionDefault
json_textYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the classification categories but doesn't disclose what the output looks like, whether it's a read-only operation, or any side effects. The output schema exists but the description doesn't explain the classification logic or edge cases. For a tool with no annotations, this is a gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise and front-loaded with the action. It lists the classification categories efficiently. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has one parameter and an output schema, so the description doesn't need to explain return values. However, with no annotations and 0% schema coverage, the description should provide more context about the input format and classification behavior. It's adequate but leaves gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only mentions 'KiCad DRC/ERC JSON' as input. The parameter 'json_text' is a string, but the description doesn't clarify expected format (e.g., raw JSON string, pretty-printed, etc.) or any constraints. The description adds minimal meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: classifying KiCad DRC/ERC JSON into one of four categories (clean, findings, malformed, unavailable). It uses a specific verb ('Classify') and resource ('KiCad DRC/ERC JSON'). It doesn't explicitly distinguish from siblings, but the sibling names are about parsing/generating sexpr data, so the classification purpose is distinct enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: when you have KiCad DRC/ERC JSON and need a classification. It doesn't explicitly state when not to use it or mention alternatives. Sibling tools like parse_kicad_sexpr handle different formats, so the context is somewhat clear but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_pin_header_footprintA

Generate a through-hole pin-header footprint as KiCad .kicad_mod S-expression text.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNo
rowsNo
pitch_mmNo
pin_countYes
descriptionNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must carry behavioral disclosure. It does tell the agent that the tool produces textual S-expression data rather than, say, writing a file directly, but it does not disclose side effects, validation behavior, or any constraints such as minimum pin count.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. Every word carries meaning, and the essential object, action, and output format are communicated immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The presence of an output schema reduces the need to describe return values, and the tool is relatively simple. Still, without parameter semantics or usage guidance, the description leaves the agent to infer important details about how rows or pitch affect the generated footprint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description mentions no parameters at all. Fields like pin_count, rows, and pitch_mm are somewhat inferable from their names and defaults, but the description adds no semantic detail about how they affect the generated footprint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Generate') on a specific resource ('through-hole pin-header footprint') and the exact output format ('KiCad .kicad_mod S-expression text'). This clearly distinguishes it from sibling tools like parse_kicad_sexpr and roundtrip_kicad_sexpr, which perform different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied by the verb 'Generate' and the S-expression output, which contrasts with the parsing/classifying siblings. However, there is no explicit guidance on when to choose this tool over alternatives or any exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parse_kicad_sexprB

Parse KiCad S-expression text into a structured CST-like representation.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It reveals that the output is CST-like, which hints at structure preservation, but it does not disclose behavior on malformed input, validation strictness, error handling, or whether positions/comments are preserved. These details matter for a parser and are absent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. Every word contributes meaning, and the core action and output are stated immediately. This is appropriately concise for a tool with one parameter and an output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a single, self-explanatory parameter and an output schema present, the description is mostly sufficient for a basic call. The main gaps are lack of error-behavior details and no mention of how this relates to the roundtrip sibling. Still, the core information an agent needs to invoke it correctly is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides no description for the 'text' parameter, and schema description coverage is 0%. The description adds some meaning by clarifying that the text should be KiCad S-expression text, not arbitrary S-expressions. However, it does not specify whether the parameter expects raw file contents, a path, or how large inputs are handled.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Parse'), a specific resource ('KiCad S-expression text'), and a concrete output ('structured CST-like representation'). It clearly identifies what the tool does and is easily distinguishable from siblings like roundtrip_kicad_sexpr, which implies serialization back to text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case: parse KiCad S-expression text when you need a structured representation. However, it gives no explicit guidance on when to choose this over roundtrip_kicad_sexpr or any of the other sibling tools, and there are no stated exclusions or context about typical invocation scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

roundtrip_kicad_sexprC

Parse and re-serialize KiCad S-expression text to validate byte-preserving round-trips.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden of behavioral disclosure. It mentions the parse and re-serialize operation but does not disclose what the tool returns (e.g., a boolean, a comparison result), how errors are handled, or any side effects. This is a significant gap for a validation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no unnecessary words. It front-loads the action and purpose, making it easy to grasp at a glance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although an output schema exists (which covers return values), the description is sparse for a validation tool. It does not define what constitutes a successful round-trip, mention any failure modes, or provide context on how the validation result should be interpreted. With no annotations, this is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description only clarifies that the 'text' parameter is KiCad S-expression text, which is a modest addition. It does not elaborate on encoding, size limits, or format specifics, so it only partially compensates for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (parse and re-serialize) and the specific purpose (validate byte-preserving round-trips) on KiCad S-expression text. It is distinct from a simple parser like parse_kicad_sexpr by focusing on round-trip fidelity, though it does not explicitly name the sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'to validate byte-preserving round-trips' implies the intended use case, but the description does not explicitly state when to use this tool versus parse_kicad_sexpr or any alternatives. No exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv0.1.0
    • First observedclassify_drc_report
    • First observedgenerate_pin_header_footprint
    • First observedparse_kicad_sexpr
    • First observedroundtrip_kicad_sexpr
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct purpose: parsing S-expressions, validating round-trips, classifying DRC reports, and generating footprints. Even parse_kicad_sexpr and roundtrip_kicad_sexpr are clearly separated by their output intent (CST representation vs. byte-preserving validation).

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern with clear domain objects: parse_kicad_sexpr, roundtrip_kicad_sexpr, classify_drc_report, and generate_pin_header_footprint. There are no mixed conventions or vague verbs.

Tool Count5/5

Four tools is an appropriate, focused size for a KiCad utility server. Each tool provides a distinct operation without unnecessary bloat or redundancy.

Completeness4/5

The set covers S-expression parsing, round-trip validation, DRC/ERC classification, and a common footprint generation task. The main gap is the narrow footprint-generation scope—only pin headers are supported—so broader KiCad footprint workflows are not covered, but this is a minor limitation for the apparent utility toolkit.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-kicad-cli

    SpectraSynq
    A
    license
    B
    quality
    C
    maintenance
    Enables KiCad CLI automation via MCP, providing tools for ERC, DRC, BOM export, netlist export, Gerbers, drill files, STEP, IPC-2581, and GLB output.
    10
    Apache 2.0

  • KiCAD MCP Server

    Avinash1286
    A
    license
    B
    quality
    B
    maintenance
    Enables AI assistants to interact with KiCAD for PCB design automation, including schematic editing, component placement, routing, DRC/ERC, and export.
    100
    11 npm
    1
    MIT

  • kicad-forge

    mpeyal
    A
    license
    B
    quality
    C
    maintenance
    Provides schematic/PCB analysis, authoring, and SPICE simulation through MCP, enabling direct KiCad file manipulation and verification without requiring KiCad for reading.
    18
    MIT