KiCad AI Assistant

KiCad AI Assistant is a KiCad action plugin that embeds an LLM-powered chat panel directly inside KiCad. It runs a built-in MCP server and exposes a rich set of tools so the LLM can read and edit your schematics and PCB layouts through natural-language conversation.

Tested on KiCad 10.0 / Linux & Windows.

Table of Contents

• KiCad AI Assistant
  • Table of Contents
  • Prerequisites
  • Installation
    • 1. Clone the repository
    • 2. Install the plugin
    • 3. Create the plugin virtual environment
    • 4. Load the plugin in KiCad
  • Configuration
  • Standalone MCP Server
  • Feature Highlights
  • Available Tools
    • Project Tools
    • Symbol Library
    • Schematic Editing
    • Schematic Analysis
    • Hierarchical Sheets
    • PCB Library
    • PCB Query
    • PCB Editing
    • PCB Placement
    • PCB Groups
    • PCB Zones
    • DRC & Design Rules
    • Versioning & Export
    • Skill System
    • KiCad IPC
  • Project Structure
  • Troubleshooting
  • Contributing
  • License

Prerequisites

• KiCad 10.0 or higher
• uv — manages the Python virtual environment and installs the correct Python version automatically
  • curl -Lsf https://astral.sh/uv/install.sh | sh
• An API key for OpenAI, Anthropic, or a compatible LLM provider

Installation

1. Clone the repository (optional)

Only needed if you want to build the plugin from source or contribute to the project. Skip this step if you're downloading the pre-built plugin from the Releases page.

git clone https://github.com/paul356/kcaa.git
cd kcaa

2. Install the plugin

Download kicad_ai_assistant.zip from the Releases page and unzip it into KiCad's plugin directory:

Linux:

KICAD_PLUGIN_DIR=~/.local/share/kicad/10.0/scripting/plugins
mkdir -p "$KICAD_PLUGIN_DIR"
unzip kicad_ai_assistant.zip -d "$KICAD_PLUGIN_DIR"

Windows (PowerShell):

$KICAD_PLUGIN_DIR = "$env:USERPROFILE\Documents\KiCad\10.0\scripting\plugins"
New-Item -ItemType Directory -Force -Path $KICAD_PLUGIN_DIR
Expand-Archive -Path kicad_ai_assistant.zip -DestinationPath $KICAD_PLUGIN_DIR

Or build from source:

# In the kcaa repository root:
make dist-plugin          # produces dist/kicad_ai_assistant.zip

# Linux:
KICAD_PLUGIN_DIR=~/.local/share/kicad/10.0/scripting/plugins
mkdir -p "$KICAD_PLUGIN_DIR"
unzip dist/kicad_ai_assistant.zip -d "$KICAD_PLUGIN_DIR"

3. Create the plugin virtual environment

Run the setup script from inside the installed plugin directory to create a .venv, install kcaa from PyPI, and download the freerouting JAR. uv will automatically install the required Python version.

Linux:

cd ~/.local/share/kicad/10.0/scripting/plugins/kicad_ai_assistant
./setup_plugin.sh

Windows (PowerShell):

cd "$env:USERPROFILE\Documents\KiCad\10.0\scripting\plugins\kicad_ai_assistant"
.\setup_plugin.ps1

Windows (Command Prompt):

cd /d "%USERPROFILE%\Documents\KiCad\10.0\scripting\plugins\kicad_ai_assistant"
setup_plugin.bat

The script will detect your KiCad version from the plugin directory path. KiCad already provides all necessary environment variables (KICAD_VERSION, KICAD*_DIR, etc.), so no .env file is needed.

4. Load the plugin in KiCad

1. Open KiCad and load your project.
2. Open the PCB Editor.
3. Go to Tools → External Plugins → Refresh Plugins.
4. Click KiCad AI Assistant in the plugin list to open the chat panel.
5. Go to Options → Settings and enter your LLM API key.

Configuration

Plugin settings are stored in the KiCad user config directory:

Settings file: ~/.config/kicad/kicad_ai_assistant.json

All settings can be changed through Options → Settings in the plugin panel:

Standalone MCP Server

You can also run kcaa as a standalone MCP server without the KiCad plugin. This is useful for integrating with other MCP clients (e.g., Claude Desktop, Cursor).

Create a .env file in your working directory:

KICAD_SEARCH_PATHS=/home/user/pcb
KICAD_APP_PATH=/usr/share/kicad
KICAD_VERSION=10.0
KICAD_CONFIG_DIR=~/.config/kicad/10.0
KICAD_3RD_PARTY=~/.local/share/kicad/10.0/3rdparty
MCP_TRANSPORT=streamable-http

Then start the server:

kcaa

Feature Highlights

• Schematic editing — Add/remove symbols, set/rename properties, draw and delete wires, connect pins automatically
• Hierarchical sheets — Create, read, update, and delete hierarchical sheet symbols and sheet pins
• PCB footprint library — Search the system footprint library index by name, description, or tag; set footprints on schematic symbols
• PCB synchronisation — Trigger Update PCB from Schematic via KiCad's IPC API
• PCB placement — Query, move, rotate, flip, align, and distribute footprints; define or clear the board outline
• Design rules — View and modify board-level design rules, net classes, and custom DRC rules
• DRC — Run design-rule checks directly from the plugin
• Context management — Automatic compaction of the LLM context window when it approaches the limit
• Session management — Save, restore, and reset the current conversation; save design snapshots for rollback
• Skill system — On-demand workflow guidance for the LLM via user-definable Markdown skill files

Available Tools

Project Tools

Symbol Library

Schematic Editing

Schematic Analysis

Hierarchical Sheets

PCB Library

PCB Query

PCB Editing

PCB Placement

PCB Groups

PCB Zones

DRC & Design Rules

Versioning & Export

Skill System

KiCad IPC

Project Structure

kcaa/
├── main.py                  # MCP server entry point
├── pyproject.toml           # Package metadata and dependencies
├── run_tests.py             # Test runner script
├── kcaa/                    # MCP server package
│   ├── server.py            # Server setup and tool registration
│   ├── config.py            # Configuration and KiCad path detection
│   ├── context.py           # Request context management
│   ├── tools/               # All MCP tool implementations
│   ├── resources/           # MCP resource handlers
│   ├── prompts/             # MCP prompt templates
│   └── utils/               # Utility functions
├── kicad_plugin/            # KiCad action plugin
│   ├── __init__.py          # Plugin entry point (KiCadAIPlugin)
│   ├── server_manager.py    # Start/stop the kcaa subprocess
│   ├── llm_client.py        # Agentic tool-call loop (OpenAI / Anthropic)
│   ├── context_bridge.py    # Collect active project paths from KiCad
│   ├── settings.py          # Load/save plugin settings
│   ├── autorouter.py        # FreeRouting integration
│   ├── tool_registry.py     # Tool metadata and categorization
│   ├── setup_plugin.sh      # Linux/macOS setup script
│   ├── setup_plugin.ps1     # Windows PowerShell setup script
│   ├── setup_plugin.bat     # Windows batch setup script
│   └── ui/                  # wxPython chat panel and settings dialog
├── docs/                    # Feature documentation
└── tests/                   # Unit tests

Troubleshooting

Plugin does not appear in KiCad:

• Confirm the plugin directory is named exactly kicad_ai_assistant (not kicad_ai_plugin).
• Run Tools → External Plugins → Refresh Plugins after installing.
• Linux: Check that setup_plugin.sh completed without errors and that .venv/bin/python exists inside the plugin directory.
• Windows: Check that setup_plugin.bat (or setup_plugin.ps1) completed without errors and that .venv/Scripts/python.exe exists inside the plugin directory.

MCP server fails to start:

• Linux: Check the plugin log in ~/.config/kicad/ for Python tracebacks.
• Windows: Check the plugin log in %APPDATA%/kicad/ for Python tracebacks.

Schematic editor does not refresh after edits:

• This is a current KiCad IPC limitation. Use File → Reload or press Ctrl+Z / Ctrl+Y to trigger a refresh in the schematic editor.

LLM API errors:

• Confirm the API key is correct in Options → Settings.
• Check that llm_model is a valid model name for your chosen provider.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add your changes with tests
4. Submit a pull request against the develop branch

PR requirements:

• One pull request should contain only one fix, enhancement, or feature. If you have multiple independent changes, please submit them as separate pull requests.
• Include tests for your changes.

Branch policy:

• The develop branch is where new features are stabilized — please submit your changes there first so they can be tested and reviewed.
• The main branch is reserved for releasing versions. Changes are merged from develop into main once they have passed testing.

License

This project is open source under the MIT license.