KiCad MCP Server

How to use

To use the MCP server, you run it locally and connect your MCP client with the provided configuration. The server exposes commands to load boards, create multi-board systems, and perform circuit analysis, net tracing, and cross-board signal tracing. Use a client to request overviews, list components and nets, examine specific components or nets, and trace connections within a single board or across multiple boards.

How to install

# Prerequisites
- Python 3.10+
- pip
- uv (recommended) for running the MCP server locally

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

Configuration and usage notes

Configure the MCP client to connect to your local server. You provide a server entry that tells the client how to start the MCP process. The example below demonstrates using uv to run the KiCad MCP server from a local directory.

{
  "mcpServers": {
    "kicad": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/kicad-mcp",
        "run",
        "kicad-mcp"
      ]
    }
  }
}

Configuration files and boards

Create a configuration file named ".kicad_mcp.yaml" in your project directory to define boards and multi-board systems, plus optional caching. You can enable caching to speed up repeated analyses and invalidate it when source files change.

boards:
  main:
    path: /path/to/main.kicad_sch
    description: Main controller board

  sensor:
    path: /path/to/sensor.kicad_sch
    description: Sensor board

systems:
  complete:
    boards: [main, sensor]
    description: Full system with all boards

cache:
  enabled: true
  directory: ~/.cache/kicad_mcp
  check_mtime: true

Runtime configuration and tools

You can load boards or systems, reload configuration without restarting, and query single-board or multi-board analyses. The server supports dynamic changes so you can add or remove boards and update systems on the fly.

Security and best practices

Run the MCP server on a trusted machine or within a secured network. Limit access to clients you trust, and consider enabling file caching only in secure environments to avoid exposing cached schematic data.

Troubleshooting tips

If the server fails to start, verify that Python 3.10+ is installed, the uv tool is available, and the path to your KiCad MCP directory is correct. Check that the client configuration points to the running MCP server and that the required files exist at the specified paths.

load_board

Load a board by name and prepare it for analysis, with optional caching to speed up subsequent queries.

load_system

Load a multi-board system defined by named boards and reuse it for cross-board analysis.

get_overview

Get a high-level summary of a loaded board or system, including component counts and nets.

list_components

List all components on a loaded board, with optional filtering by category.

list_nets

List nets on a loaded board, with optional filtering for power nets.

examine_component

Return detailed information for a specific component, including pins and connected nets.

examine_net

Return detailed information for a specific net, including connected components and pin names.

trace_connection

Find a path between two components on the same board.

trace_cross_board_signal

Trace a signal across multiple boards within a defined system.

reload_config

Reload the current configuration without restarting the MCP server.