Finerestaurant/kicad-mcp-python

KiCad MCP Server

This project is a Model Context Protocol (MCP) server for KiCad. As MCP server that utilizes KiCad's official IPC-API, it provides the most stable and reliable way for AI models like Claude to interact with KiCad, automating and assisting with PCB design and schematic tasks.

Key Features

• MCP Server Implementation: Handles requests from MCP clients.
• KiCad Integration: Communicates with a running KiCad session using the kicad-python library.
• Automated Workflows: Enables AI models to create, modify, and verify schematics and PCB layouts in KiCad projects.

Wiring

https://github.com/user-attachments/assets/e2ba57e7-2c77-4c56-a911-c461c77307e4

Move item

https://github.com/user-attachments/assets/de6c93dc-8808-4321-827e-ebad0556e7b1

What Can It Do?

With this MCP server, an AI model can perform tasks such as:

• Manipulate PCB Objects:
  • Create new items (footprints, tracks, etc.)
  • Modify the properties of existing items
  • Move and rotate items
  • Delete unnecessary items
• Analyze PCBs:
  • Get a list of all items of a specific type on the board
  • Query the overall status information of the board

Getting Started

This project uses Poetry to manage dependencies.

1. Prerequisite: Install kicad-python

This project uses the kicad-python library as a Git submodule. Therefore, you must build and install kicad-python before running this project.

1. Clone Repository and Initialize Submodules: Run git submodule update --init to add kicad-python's source code as a submodule.

   git submodule update --init --depth 1
   

2. Build and Install kicad-python: Navigate to the kicad-python directory and follow the instructions in that project's COMPILING.md file to build and install the library.

2. Configure Environment Variables

Before running the server, you need to create a .env file in the project's root directory (KiCad-mcp-python/.env). This file is crucial for tools that rely on KiCad's command-line interface (CLI), such as the verify_result tool which generates screenshots to confirm the results of an operation. It stores the necessary environment variables for the server to function correctly.

Create a file named .env and add the following content, adjusting the paths to match your system configuration:

KICAD_CLI_PATH=/path/to/your/kicad-cli
PCB_PATHS=/path/to/your/project1.kicad_pcb,/path/to/your/project2.kicad_pcb

Variable Explanations:

• KICAD_CLI_PATH: The absolute path to the KiCad command-line interface (CLI) executable.
  • macOS Example: /Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli
  • Windows Example: C:\Program Files\KiCad\7.0\bin\kicad-cli.exe
  • Linux Example: /usr/bin/kicad-cli
• PCB_PATHS: A comma-separated list of absolute paths to the .kicad_pcb files you want the MCP server to be able to access.

3. Install and Run the MCP Server

1. Install Dependencies: Once kicad-python is installed, return to this project's root directory and run the following command to install the remaining dependencies:

   poetry install
   

2. Enable KiCad IPC Server: Launch KiCad and enable the IPC server by selecting Tools -> External Plugin -> Start Server.

3. Start the MCP Server: Start the MCP server with the following command:

   poetry run python main.py
   

The server is now waiting for a connection from an MCP client.

4. MCP Client Configuration

To use this server with an MCP client (e.g., a VSCode extension), you need to configure the server execution command correctly.

1. Find the Poetry Virtual Environment Interpreter Path: Run the following command to find the full path to the Python interpreter installed in the current project's Poetry virtual environment:

   poetry env info --path
   

   Copy the path output by the command (e.g., /pypoetry/virtualenvs/kicad-mcp-python-xxxxxxxx-py3.10).

2. Add MCP Server Configuration: Add the server information to your MCP client's configuration file (e.g., mcp_servers.json) as follows:

   • command: Enter the full path to the interpreter by appending /bin/python to the path you copied above.
   • args: Add ["main.py"] to specify the script to run.

   Configuration Example:

   {
     "servers": [
       {
         "name": "kicad-mcp-server",
         "command": "/pypoetry/virtualenvs/kicad-mcp-python-xxxxxxxx-py3.10/bin/python",
         "args": ["main.py"],
   
       }
     ]
   }
   

Future Plans

• Schematic Support: Currently developing APIs related to schematics in KiCad, and we plan to implement these features in the MCP as soon as development is complete.

• Simultaneous Multi-Item Editing/Moving: We will implement functionality to select and modify or move multiple PCB items at once.

• Workflow Improvements: We will improve the step-by-step flow of tools like item creation and modification to provide a more efficient and intuitive API.

• ScreenShot Verification: We will implement a step to automatically verify the results after item manipulation to increase the reliability of operations.

Changelog

[0.2.0] (Planned)

• Implement functionality to select and modify or move multiple PCB items at once.
• Add a verify_result tool that uses screenshots for visual confirmation after operations. (0708 commit)

[0.1.0] - 2025-07-02

• Initial release of the KiCad MCP server.
• Support for basic PCB object manipulation (create, modify, move, delete).
• Detailed setup instructions including kicad-python submodule installation.