macOS · KiCad 10 · Claude Code

Wiring Konnect into KiCad and Claude Code

Konnect bridges KiCad's editors to Claude over MCP. One binary does both jobs — KiCad's Plugin Manager keeps it updated, and Claude Code launches that same copy directly. Configure the pieces below and they agree on one socket. This is the exact path, verified on a real machine.

One binary, two launchers. KiCad's Plugin Manager installs and updates bin/konnect; Claude Code can launch that exact file directly — no separate download needed. Both sides just need to agree on the same ipc:// address.

PART 1

Install the KiCad-side plugin

This gives KiCad a Tools menu entry and a live schematic/PCB viewer. It does not by itself talk to Claude.

In KiCad: Tools → Plugin and Content Manager
Search Konnect, click Install, then Apply Changes.
Fully quit KiCad (⌘Q — not just closing the project) and relaunch, so the plugin registers.

Installs to

~/Documents/KiCad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/

PART 2

Turn on KiCad's IPC API

This is KiCad's own feature — Konnect just connects to it. It's off by default.

KiCad → Preferences → Plugins
Check Enable KiCad API. Note the socket address shown — normally ipc:///tmp/kicad/api.sock.
Fully quit (⌘Q) and relaunch KiCad. The API server thread only starts on a fresh launch — toggling the box isn't enough on its own.
Verify the socket exists:

# after relaunch
ls /tmp/kicad/
# → api.lock  api.sock

The checkbox itself is stored in:

~/Library/Preferences/kicad/10.0/kicad_common.json
{
  "api": { "enable_server": true, ... }
}

PART 3

Point the plugin at the socket

Tell the KiCad-side plugin where the API actually lives.

With KiCad open: Tools → External Plugins → Konnect
Paste into IPC Socket: ipc:///tmp/kicad/api.sock
Click Save.

Writes to

~/Documents/KiCad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/settings.json

PART 4

Make the plugin binary executable

Claude Code launches this file directly, but the Plugin Manager doesn't install it with the execute bit set — so the very first launch attempt fails with a permission error. One-time fix:

chmod +x ~/Documents/KiCad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/bin/konnect
chmod +x ~/Documents/KiCad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/bin/schematic-viewer

# confirm it runs
~/Documents/KiCad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/bin/konnect --version

Re-run this after any Plugin Manager update to Konnect — updates re-extract the archive and drop the execute bit again.

PART 5

The config file almost everyone misses

The standalone binary does not read the settings you saved in Part 3 — that file belongs to the KiCad plugin. The binary reads its own config, in a different format, from a different folder.

This is the step that breaks silently

If Konnect's tools report ipc_available: false even though /tmp/kicad/api.sock exists, this file is almost always missing — or saved as .json instead of .toml.

Create it

mkdir -p ~/Library/Application\ Support/konnect

cat > ~/Library/Application\ Support/konnect/config.toml <<'EOF'
ipc_socket_path = "ipc:///tmp/kicad/api.sock"
kicad_cli = "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"
EOF

This file is read once, at process start. Any edit needs a restart to take effect — see Part 8.

PART 6

Register Konnect with Claude Code

Add an mcpServers entry pointing straight at the Plugin-Manager-installed binary from Part 4 — the same file KiCad itself uses.

Global config — ~/.claude.json

{
  ...
  "mcpServers": {
    "konnect": {
      "type": "stdio",
      "command": "/Users/<you>/Documents/KiCad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/bin/konnect",
      "args": [],
      "env": {}
    }
  }
}

Project-scoped instead of global? Put the same "konnect": {…} object in a .mcp.json at the project root. Either way, one binary now serves both KiCad and Claude Code — nothing extra to keep in sync when Konnect updates.

PART 7

Put kicad-cli on PATH

ERC, DRC, and every export/render tool shells out to kicad-cli — but installing KiCad.app doesn't put it on PATH.

# pick any directory already on your PATH
ln -sf /Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli ~/bin/kicad-cli

PART 8

Restart both sides and verify

Fully quit and relaunch KiCad, with the project open
Restart Claude Code, so the MCP server rereads config.toml
Ask Claude to check the KiCad connection — it should report ipc_available: true and list your open board

REFERENCE

Troubleshooting

Symptom	Cause & fix
Claude Code can't launch konnect at all — permission denied	The Plugin-Manager copy loses its execute bit on install and on every update. Redo Part 4's `chmod +x`.
Socket exists, but tools still say IPC unreachable	config.toml missing, or saved as `.json`. It must be TOML, at the exact path in Part 5. Recreate it, then restart Claude Code.
"Board is open in the schematic editor" — but it isn't	Stale `.lck` files from a crashed KiCad session. Quit KiCad, then check for and delete `~*.lck` in the project folder.
Socket file disappears after a KiCad relaunch	The IPC checkbox reverted, or KiCad wasn't fully quit last time (Dock icon still bouncing counts as still running). Recheck Part 2.
Flipping a footprint to the other side always refuses	That specific operation has no live-IPC path yet. Either close KiCad and let the tool edit the file directly, or select the part in KiCad and press F yourself.
ERC / DRC / SVG export fail outright	`kicad-cli` isn't on PATH. Redo Part 7, then confirm with `which kicad-cli`.
Edited config.toml, still no change	The MCP server only reads config at startup. Restart Claude Code — reopening the KiCad project alone won't do it.