KiCAD MCP Server

How to use

To use the KiCAD MCP Server, you run it as a local process that speaks the Model Context Protocol (MCP) with your AI assistant client. You can interact with it through a prepared client configuration that points to a local stdio server or through a remote HTTP endpoint if you choose to expose the server over the network. The server exposes a large set of tools organized into discoverable categories, plus read‑only resources that let you inspect current project state without executing actions. You’ll describe what you want to achieve in natural language, and your AI assistant will discover the appropriate tool and parameters, then execute the operation or return the relevant state data. When you ask to place components, route traces, or generate outputs, the server handles the underlying KiCAD interactions and returns results or updated project state for you to review.

How to install

Follow these steps to install and run the KiCAD MCP Server on your platform. The process includes prerequisites, building dependencies, and a final check to ensure the Python KiCAD bindings are accessible.

# Prerequisites for all platforms
- KiCAD 9.0 or higher with Python support (pcbnew available)
- Node.js 18 or higher
- Python 3.10 or higher
- MCP client option (Claude Desktop, Claude Code, or Cline)

# Linux example (Ubuntu/Debian)
# 1) Install KiCAD 9.0
sudo add-apt-repository --yes ppa:kicad/kicad-9.0-releases
sudo apt-get update
sudo apt-get install -y kicad kicad-libraries

# 2) Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 3) Clone the MCP server repository
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server

# 4) Install dependencies
npm install
pip3 install -r requirements.txt

# 5) Build the server
npm run build

# 6) Verify KiCAD access
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())" 

# Windows example (PowerShell)
# 1) Clone the repository
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server

# 2) Automated setup (recommended)
.\setup-windows.ps1

# macOS example
# 1) Install KiCAD 9.0 from KiCad download page
# 2) Install Node.js
brew install node@20

# 3) Clone repository
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server

# 4) Create a virtual environment using KiCAD's bundled Python
/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -m venv venv --system-site-packages

# 5) Activate and install
source venv/bin/activate
npm install
pip install -r requirements.txt
npm run build

# 6) Note: ensure KiCAD Python access from the virtual environment
"} ]},{

Configuration and runtime setup

Configure the MCP client to connect to the server instance. The following example shows a local stdio configuration where you run the MCP server via Node and point the client at the built index script.

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/path/to/kicad/python",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Troubleshooting and tips

If you run into issues, check that the MCP server process is running, the build artifacts exist, and the client configuration uses absolute paths. Verify KiCAD’s pcbnew module is accessible from Python with a simple import. Review logs for errors and ensure that the Python bindings and environment variables are correctly set for your platform.

Notes on availability and development state

The MCP server ships with cross‑platform support and progressive enhancements. Real‑time KiCAD UI synchronization via experimental IPC is under active development and may require enabling the IPC API server in KiCAD preferences. Tool discovery is designed to minimize AI context usage while preserving full functionality. The JLCPCB parts integration provides local and remote catalog access for component selection and pricing.

Security and best practices

Run the MCP server on a trusted machine with proper access controls. If exposing the server over a network, ensure secure communication channels, and avoid leaking API endpoints or local paths in shared environments. Keep dependencies up to date and monitor logs for unusual activity.

Examples and quick start prompts

You can start by asking your AI assistant to create a new KiCAD project, define board size, place mounting holes, and add power nets. Then instruct the assistant to place a schematic symbol dynamically from KiCAD libraries, wire components with intelligent routing, and generate Gerber outputs. You can also query the server for current project state, such as the list of components or net names, without making changes.

Appendix: Available configuration options for the client

The client configuration includes the MCP server connection, Python path hints for KiCAD, and log level controls. Use absolute paths and ensure the runtime command matches the server startup procedure used in your environment.

create_project

Initialize a new KiCAD project with both PCB and schematic files.

open_project

Load existing KiCAD project files into the MCP context.

save_project

Save the current project state to disk and MCP state.

get_project_info

Retrieve metadata about the current project.

set_board_size

Configure the board dimensions for the PCB.

add_board_outline

Create a board outline or perimeter.

add_layer

Add a new layer to the board stack.

set_active_layer

Switch the currently active working layer.

get_layer_list

List all layers present in the board.

get_board_info

Retrieve properties of the current board.

get_board_2d_view

Generate a 2D board preview image.

add_mounting_hole

Place mounting holes at specified coordinates.

add_board_text

Add text annotations on the board.

place_component

Place a component with a footprint at a given position.

move_component

Reposition an existing component.

rotate_component

Rotate a component by a specified angle.

delete_component

Remove a component from the board.

edit_component

Modify properties of a placed component.

get_component_properties

Query details for a specific component.

get_component_list

List all components currently placed.

place_component_array

Create a grid or pattern of components.

align_components

Align multiple components with specified rules.

duplicate_component

Copy a component to another location.

add_net

Create a new electrical net.

route_trace

Route copper traces between pins.

add_via

Place vias for layer transitions.

delete_trace

Remove traces from the board.

get_nets_list

List all nets in the design.

create_netclass

Define a net class with routing rules.

add_copper_pour

Create copper pours for filled areas.

route_differential_pair

Route a differential signal pair.

list_libraries

List available footprint libraries.

search_footprints

Search footprints by name or attribute.

list_library_footprints

List footprints within a library.

get_footprint_info

Get details for a footprint.

download_jlcpcb_database

Download the complete JLCPCB parts catalog (one-time setup).

search_jlcpcb_parts

Search the JLCPCB catalog with filters.

get_jlcpcb_part

Get pricing and footprint details for a part.

get_jlcpcb_database_stats

View statistics for the JLCPCB database.

suggest_jlcpcb_alternatives

Find cheaper or more available part alternatives.

set_design_rules

Configure design rule checks (DRC) parameters.

get_design_rules

Retrieve current DRC settings.

run_drc

Execute a design rule check.

get_drc_violations

Get a report of DRC violations.

export_gerber

Generate Gerber fabrication files.

export_pdf

Export design documentation as PDF.

export_svg

Export SVG representations of the design.

export_3d

Generate 3D models (STEP/VRML).

export_bom

Produce a bill of materials.

create_schematic

Initialize a new schematic from templates.

load_schematic

Open an existing schematic.

add_schematic_component

Place symbols with dynamic KiCAD library loading.

list_schematic_libraries

List symbol libraries available for schematics.

export_schematic_pdf

Export the schematic as a PDF.

add_schematic_wire

Create wires between points with customizable stroke.

add_schematic_connection

Auto-connect pins with intelligent routing.

add_schematic_net_label

Add net labels with orientation control.

connect_to_net

Connect component pins to named nets.

check_kicad_ui

Check if KiCAD UI is running.

launch_kicad_ui

Launch the KiCAD application.