KiCad MCP

KiCad MCP is a local MCP server and KiCad action plugin for automating KiCad projects from AI tools. It can inspect projects, run ERC/DRC, export BOM and fabrication files, edit schematics/boards, inspect connectivity/layers/drills, report capability inventory, assess fabrication and assembly readiness, author symbol libraries, footprint libraries, and placed board footprint pads with custom pads/holes/slots, perform advanced measurement/analytic-clearance/dimension/keepout/routing-edit/zone-fill/arrangement workflows, and bridge to the live KiCad PCB Editor GUI.

The npm package includes:

• A Node.js npx launcher.
• The Python KiCad MCP server.
• KiCad action plugin files.
• Capability discovery through kicad_tool_inventory, including category counts, safety class, dry-run support, backup support, and KiCad CLI/GUI dependencies.
• Symbol, footprint library, and placed-board pad authoring tools for pins, custom polygon pads, mounting holes, slotted holes, pad edit/delete, graphics, metadata, and 3D models.
• An optional Codex skill installer.

Quick Start

Run the MCP server over stdio, which is the normal mode for MCP clients:

npx -y kicad-mcp

Check the published package:

npm view kicad-mcp version
npx -y kicad-mcp --version

Install the optional Codex skill:

npx -y kicad-mcp --install-codex-skill

MCP Client Config

Use this config for clients that launch MCP servers with stdio:

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

If KiCad CLI is not in the default location, pass it with env:

{
  "mcpServers": {
    "kicad": {
      "command": "npx",
      "args": ["-y", "kicad-mcp"],
      "env": {
        "KICAD_CLI": "/path/to/kicad-cli"
      }
    }
  }
}

Codex Skill

Install the bundled Codex skill locally:

npx -y kicad-mcp --install-codex-skill

This copies the skill to:

~/.codex/skills/kicad-mcp

If Codex uses a custom home directory, set CODEX_HOME or pass it explicitly:

CODEX_HOME="/path/to/codex-home" npx -y kicad-mcp --install-codex-skill
npx -y kicad-mcp --install-codex-skill --codex-home /path/to/codex-home

Use the actual Codex home directory for your environment.

Restart Codex if the skill is not visible yet, then invoke it with:

Use $kicad-mcp to inspect this KiCad project and run safe checks.

The skill teaches Codex to use KiCad MCP safely: read first, use dry_run=true for supported edits, keep backups enabled, and run ERC/DRC after changes.

HTTP Mode

For local HTTP service mode:

npx -y kicad-mcp --http --host 127.0.0.1 --port 8765

The server URL is:

http://127.0.0.1:8765/mcp

Keep HTTP bound to 127.0.0.1 unless you add authentication.

Python Environment

The launcher looks for Python 3.10 or newer, creates a virtualenv in the user cache directory, and installs pinned Python requirements from kicad-ai-plugin/requirements.txt.

Useful commands:

npx -y kicad-mcp --setup
npx -y kicad-mcp --python /path/to/python3.13
npx -y kicad-mcp --venv /path/to/venv
npx -y kicad-mcp --kicad-cli /path/to/kicad-cli

Default cache locations:

• macOS: ~/Library/Caches/kicad-mcp/venv
• Linux: ~/.cache/kicad-mcp/venv
• Windows: %LOCALAPPDATA%\kicad-mcp\venv

KiCad GUI Bridge

The live GUI tools require the KiCad action plugin to be installed and run from KiCad PCB Editor. See kicad-ai-plugin/README.md for the plugin layout and complete tool list.

GUI tools require:

• KiCad PCB Editor open.
• A board loaded.
• The KiCad AI MCP action plugin started from KiCad.

Local Repo Commands

From this repository:

npm run check
npm pack --dry-run
node bin/kicad-mcp.js --setup
node bin/kicad-mcp.js --install-codex-skill
node bin/kicad-mcp.js --install-codex-skill --codex-home /path/to/codex-home

The older local service scripts are still available:

./build_and_run.sh
./start_mcp.sh
./status_mcp.sh
./stop_mcp.sh

Release Checklist

Before publishing a new npm version:

npm run check
npm pack --dry-run
npm version patch
npm publish
git push origin main --tags

If npm asks for two-factor authentication, publish with the current 6-digit OTP:

npm publish --otp=123456

If using an npm granular access token, keep it local and revoke it after use.

Troubleshooting

Package is published:

npm view kicad-mcp name version license

Launcher works:

npx -y kicad-mcp --version

Codex skill installed:

ls ~/.codex/skills/kicad-mcp
# Or, for a custom Codex home:
ls /path/to/codex-home/skills/kicad-mcp

Local HTTP server is reachable:

curl -i http://127.0.0.1:8765/mcp

An HTTP 406 can be normal for a plain browser/curl GET because MCP clients use the MCP protocol headers and request flow.

License

MIT. See LICENSE.