Linux · KiCad 10 · Claude Code

Konnect on Linux

Same bridge as the macOS setup — one Konnect binary, installed once, used by both KiCad and Claude Code. Linux adds one real fork in the road: whether KiCad came from your distro's package manager or from Flatpak. Everything below is written from Konnect's own source and KiCad's documented behavior; the exact socket path is the one thing to confirm on your machine rather than assume.

One binary, two launchers. KiCad's Plugin Manager installs and updates bin/konnect; Claude Code launches that exact file directly. * On Flatpak installs, KiCad's sandbox can put the socket somewhere Claude Code can't see — Part 2 covers this.

PART 1

Install the KiCad-side plugin

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

Download the Linux release from github.com/mixelpixx/Konnect → Releases — konnect-pcm-<version>-linux.zip.
In KiCad: Tools → Plugin and Content Manager
Choose Install from File and select the zip you downloaded.
Restart KiCad so the plugin registers.

Installs to

~/.local/share/kicad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/

PART 2

Turn on KiCad's IPC API

KiCad's own feature — off by default, regardless of how KiCad was installed.

Edit → Preferences → Plugins
Check Enable KiCad API.
Copy the exact socket address the dialog shows you — don't assume it. It's usually ipc:///tmp/kicad/api.sock on a native package install.
Restart KiCad fully so the API server thread actually starts.

If KiCad came from Flatpak

Flatpak sandboxes give KiCad its own private /tmp, invisible to processes on the host — including the Konnect binary Claude Code launches. The socket still gets created, just not where a host process can reach it. Two ways through:

Easiest: use a distro package or the official .deb/AppImage instead of Flatpak for this integration.

If you need Flatpak: check whether the address shown in Preferences resolves under $XDG_RUNTIME_DIR rather than /tmp — that path is usually bind-mounted into the sandbox and reachable from the host. Point ipc_socket_path in Part 5 at whatever address KiCad actually shows.

The checkbox itself is stored in:

~/.config/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 the address you copied in Part 2 into IPC Socket.
Click Save.

Writes to

~/.local/share/kicad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/settings.json

PART 4

Check the plugin binary is executable

Claude Code launches this file directly. Some Plugin Manager installs extract zip archives without preserving the execute bit — this bit us on macOS, worth checking here too.

ls -l ~/.local/share/kicad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/bin/konnect
# if it doesn't already show an x in the permissions:
chmod +x ~/.local/share/kicad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/bin/konnect
chmod +x ~/.local/share/kicad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/bin/schematic-viewer

# confirm it runs
~/.local/share/kicad/10.0/3rdparty/plugins/com_github_mixelpixx_konnect/bin/konnect --version

Worth re-checking after any Plugin Manager update to Konnect.

PART 5

The config file almost everyone misses

The settings you saved in Part 3 belong to the KiCad plugin. The binary that Claude Code runs reads its own config, in a different format, from a different folder — and only at startup.

This is the step that breaks silently

If Konnect's tools report the IPC socket unreachable even though it exists, this file is almost always missing, misplaced, or saved as .json instead of .toml.

Create it

mkdir -p ~/.config/konnect

cat > ~/.config/konnect/config.toml <<'EOF'
ipc_socket_path = "ipc:///tmp/kicad/api.sock"
EOF

Use the exact address you copied from KiCad's Preferences dialog in Part 2, not necessarily the one above.

Native package install (apt / dnf / pacman)

That's usually the whole file — kicad-cli and kicad are already on PATH at /usr/bin/, and Konnect falls back to the bare command names.

Flatpak install

kicad-cli only exists inside the Flatpak sandbox — there's no plain executable path to point at directly. Wrap it in a small script and point Konnect at the script instead:

cat > ~/.local/bin/kicad-cli <<'EOF'
#!/bin/sh
exec flatpak run --command=kicad-cli org.kicad.KiCad "$@"
EOF
chmod +x ~/.local/bin/kicad-cli

Then add to config.toml:

kicad_cli = "/home/<you>/.local/bin/kicad-cli"

This file is read once, at process start — any edit needs a restart to take effect. See Part 7.

PART 6

Register Konnect with Claude Code

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

Global config — ~/.claude.json

{
  ...
  "mcpServers": {
    "konnect": {
      "type": "stdio",
      "command": "/home/<you>/.local/share/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.

PART 7

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 the IPC socket reachable and list your open board

REFERENCE

Troubleshooting

Symptom	Cause & fix
Claude Code can't launch konnect — permission denied	Execute bit missing on the Plugin-Manager copy. Redo Part 4's `chmod +x` — check again after every Konnect update.
Socket exists, but tools still say it's unreachable	config.toml missing, wrong path, or saved as `.json`. It must be TOML, at `~/.config/konnect/config.toml`. Recreate it, then restart Claude Code.
KiCad was installed via Flatpak and nothing connects	The socket lives inside KiCad's sandbox `/tmp`, not the host's. Check for it under `$XDG_RUNTIME_DIR` instead, or switch to a native/distro package for this integration.
"Board is open in the schematic editor" — but it isn't	Stale lock files from a crashed KiCad session. Quit KiCad, then look for and delete any `.~lock.#` or `~.lck` files in the project folder.
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	On a native install, confirm with `which kicad-cli`. On Flatpak, confirm the wrapper script from Part 5 runs and is what `kicad_cli` in config.toml points to.
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.