KiCAD PCB Designer MCP server

KiCAD MCP is a powerful implementation of the Model Context Protocol (MCP) that allows AI assistants like Claude to interact directly with KiCAD PCB design software. This bridge enables natural language control of advanced PCB design operations, letting you create and manipulate circuit board designs through simple text commands.

System Requirements

Before installation, ensure your system meets these requirements:

• KiCAD 9.0 or higher (full installation required)
• Node.js v18 or higher and npm
• Python 3.8 or higher with pip (KiCAD 9.0's bundled version is sufficient)
• Cline (VSCode Claude extension) or another MCP-compatible client
• Windows 10/11 (current version optimized for Windows; Linux/Mac support planned)

Installation

Install KiCAD 9.0

1. Download KiCAD 9.0 from the official KiCAD website
2. Run the installer with default installation options
3. Ensure the Python module is included (default in standard installation)

Set Up KiCAD MCP

1. Clone the repository and install dependencies:

git clone https://github.com/kicad-ai/kicad-mcp.git
cd kicad-mcp
npm install
npm run build

Configure Cline (VSCode Claude Extension)

1. Install VSCode from the official website if needed

2. Install the Cline extension from the VSCode marketplace

3. Edit the Cline MCP settings file located at:

   • Windows: %USERPROFILE%\AppData\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
   • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

4. Add this configuration (update paths for your system):

"kicad": {
  "autoApprove": [],
  "disabled": false,
  "timeout": 60,
  "command": "C:\\Program Files\\nodejs\\node.exe",
  "args": [
    "C:/path/to/kicad-mcp/dist/kicad-server.js"
  ],
  "env": {
    "PYTHONPATH": "C:/Program Files/KiCad/9.0/lib/python3/dist-packages",
    "DEBUG": "mcp:*"
  },
  "transportType": "stdio"
}

5. Restart VSCode or reload the window for changes to take effect

Verify Installation

1. Open VSCode with the Cline extension
2. Start a new conversation with Claude
3. Test with a simple command:

Create a new KiCAD project named 'TestProject' in the 'test' directory.

4. Claude should use KiCAD MCP to create the project and confirm success

Usage Examples

Project Management

Create a new KiCAD project named 'WiFiModule' in my Documents folder.

Open the existing KiCAD project at C:/Projects/Amplifier/Amplifier.kicad_pro

Board Design

Set the board size to 100mm x 80mm.

Add a rounded rectangle board outline with 3mm corner radius.

Add mounting holes at each corner of the board, 5mm from the edges.

Component Placement

Place a 10uF capacitor at position x=50mm, y=30mm.

Create a grid of 8 LEDs, 4x2, starting at position x=20mm, y=10mm with 10mm spacing.

Align all resistors horizontally and distribute them evenly.

Routing

Create a new net named 'VCC' and assign it to the power net class.

Route a trace from component U1 pin 1 to component C3 pin 2 on layer F.Cu.

Add a copper pour for GND on the bottom layer.

Design Rules and Export

Set design rules with 0.2mm clearance and 0.25mm minimum track width.

Export Gerber files to the 'fabrication' directory.

Feature Categories

Project Management

• Create new KiCAD projects with custom settings
• Open existing KiCAD projects
• Save projects with optional new locations
• Retrieve project metadata and properties

Board Design

• Set precise board dimensions with metric and imperial units
• Create custom board outlines (rectangle, rounded rectangle, circle, polygon)
• Create and manage board layers
• Add mounting holes, text annotations, and other board features
• View current board state

Components

• Place components with specific footprints at precise locations
• Create component arrays in grid or circular patterns
• Move, rotate, and modify components
• Align and distribute components evenly
• Duplicate components with custom properties
• Get detailed component properties and listings

Routing

• Create and manage nets with specific properties
• Route traces between component pads or points
• Add vias, including blind and buried vias
• Create differential pair routes for high-speed signals
• Generate copper pours (ground planes, power planes)
• Define net classes with specific design rules

Design Rules

• Set global design rules for clearance, track width, etc.
• Define specific rules for different net classes
• Run Design Rule Check (DRC) to validate designs
• View and manage DRC violations

Export

• Generate Gerber files for fabrication
• Export PDF documentation
• Create SVG vector graphics
• Generate 3D models in STEP or VRML format
• Create bill of materials (BOM) in various formats

Troubleshooting

Common Issues

KiCAD MCP isn't showing up in Claude's tools

• Restart VSCode completely after updating Cline MCP settings
• Verify the paths in the config are correct for your system
• Check that npm run build completed successfully

Node.js errors when launching the server

• Ensure you're using Node.js v18 or higher
• Run npm install again to ensure all dependencies are installed
• Check console output for specific error messages

Python errors or KiCAD commands failing

• Verify KiCAD 9.0 is properly installed
• Check that PYTHONPATH in the configuration points to the correct location
• Try running a simple KiCAD Python script directly to test pcbnew module accessibility

Claude can't find or load your KiCAD project

• Use absolute paths when referring to project locations
• Ensure the user running VSCode has access permissions to the directories

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.