KiCad Agentic MCP

KiCAD 10용 AI 지원 PCB 설계. Konnect는 네이티브 KiCAD 플러그인입니다 — 단일 Rust 바이너리로, Claude 및 기타 AI 어시스턴트가 Model Context Protocol(MCP)을 통해 회로도와 PCB를 설계할 수 있게 해줍니다.

22개의 온디맨드 툴셋에 걸친 202개 도구. 회로도 캡처, PCB 레이아웃 및 라우팅, ERC/DRC, 설계 검토 감사, JLCPCB 부품 검색, Freerouting, 참조 회로, 그리고 완전한 제조 내보내기 파이프라인 — Claude에게 KiCAD 규칙을 즉시 가르쳐 주는 번들 스킬과 에이전트가 포함되어 있습니다.

이 저장소는 KiCad Agentic MCP로, mixelpixx/Konnect v0.2.2의 에이전틱 포크이며 동일한 AGPL-3.0 라이선스를 따릅니다. Konnect의 도구 표면 위에 MCP 게이트웨이, 결정적 실행기를 갖춘 계획 IR, 증거 핸들, 작업 상태 및 로컬 모델 런타임을 추가합니다. 서버 바이너리는 여전히 konnect라고 불립니다.

상태: v1.1.1. 무엇을 측정하는지, 무엇이 빠졌는지, 무엇을 다루지 않는지는 RELEASE_NOTES.md에 있습니다. 아래에 인용된 모든 수치는 docs/benchmark.md에 근거합니다. 이슈와 PR은 환영합니다 — CONTRIBUTING.md 및 명명 규칙을 참조하세요.

하나의 프롬프트가 하는 일

examples/demo/에 커밋된 시작 보드에 대한 하나의 프롬프트 — 예시가 아니라 재현 가능합니다. 우리의 말이 아닌 KiCAD의 판정: 이전에는 연결되지 않은 항목 5개, 이후에는 0개, 트랙 세그먼트 11개, 오류 없음. 동일한 상태에서 두 번 실행했을 때 두 번 모두 동일한 회로, 다른 좌표.

두 개의 숫자, 서로 다른 두 가지를 측정하기 때문입니다: 보드 변경은 1초 미만(Konnect 시간 기준 0.69초 및 0.77초)에 적용되는 반면, 그 주변의 프롬프트는 6~7분이 걸립니다. 모델이 턴마다 세그먼트 하나를 라우팅하기 때문입니다. 두 실행 모두, 호출별로, demo-run-2.md와 demo-run-3.md에 있습니다.

Related MCP server: KiCad MCP Pro

빠른 시작

릴리스 페이지에서 KiCAD 자체가 확인하는 변경까지 다섯 단계. Konnect가 설치된 적 없는 머신에서 진행했습니다. 잘못된 부분을 포함한 기록은 docs/launch/first-run-walk.md에 있습니다.

그 워크스루가 측정한 것: KiCAD를 실행하고 플러그인을 설치하기까지 약 9번의 클릭과 대화상자, KiCAD 재시작 2회, 그리고 108 ms 만에 돌아온 첫 번째 작업. 총 시간은 클릭 속도에 좌우되므로 숫자로 인용하지 않습니다.

시작하기 전에 KiCAD 10(10.0.3으로 테스트)과 MCP 클라이언트가 필요합니다 — Claude Desktop, Claude Code, 또는 MCP를 말하는 다른 무엇이든. 그 외에는 아무것도 필요 없습니다: Node도, Python도, 패키지 트리도 없습니다. Windows가 가장 많이 테스트된 플랫폼입니다. macOS와 Linux의 상태는 요구 사항을 참조하세요.

1 — 플러그인 패키지를 다운로드합니다. Releases에서 konnect-pcm-v<version>-windows.zip(또는 -macos.zip / -linux.zip)을 받으세요. konnect-pcm-* 자산은 KiCAD 플러그인 패키지입니다. 다른 아카이브는 이 경로에 필요하지 않은 독립 실행형 서버 바이너리입니다.

2 — 설치합니다. KiCAD 10 → Plugin and Content Manager → Install from File… → zip 파일을 선택합니다. 파일을 선택하는 순간 설치됩니다 — Apply Pending Changes 버튼은 회색으로 남아 있고 확인할 것이 더 없습니다. KiCAD를 재시작합니다.

3 — KiCAD API를 켭니다. Preferences → Plugins → Enable KiCad API를 체크한 후 KiCAD를 재시작합니다. KiCAD는 이 기능을 꺼진 상태로 제공하며, 여기의 모든 PCB 도구는 이를 통해 KiCAD와 통신합니다. 회로도 편집과 내보내기는 이것 없이도 작동하지만, 실시간 보드 편집은 그렇지 않습니다. 재시작 후 같은 페이지에 Listening on ipc://…라고 표시되어야 합니다.

4 — MCP 클라이언트를 서버에 연결합니다. PCM 설치 후 바이너리는 KiCAD 문서 폴더에 있습니다:

C:\Users\<YOU>\Documents\KiCad\10.0\3rdparty\plugins\com_github_mixelpixx_konnect\bin\konnect.exe

그 경로를 클라이언트의 MCP 구성에 넣으세요 — Claude Desktop의 경우 %APPDATA%\Claude\claude_desktop_config.json, Claude Code의 경우 프로젝트 루트의 .mcp.json. 두 가지 모두의 복사-붙여넣기 버전은 examples/에 있으며, 전체 스니펫은 아래에 있습니다. 클라이언트를 재시작하면 konnect가 시작 시 21개 도구를 보고해야 합니다. 그것이 전체 스타터 키트입니다 — 나머지 카탈로그는 온디맨드로 로드되거나, tools/list에 전혀 나타나지 않고 게이트웨이를 통해 호출됩니다. 표준 KiCAD 10 설치에는 konnect-settings.json이 필요하지 않습니다: v1.1.1은 kicad-cli, KiCAD GUI 바이너리 및 IPC 주소를 자동으로 발견합니다. 비정상적이거나 휴대용 설치를 위한 명시적 설정은 계속 사용할 수 있습니다.

5 — 할 일을 주세요. KiCAD 프로젝트를 연 상태에서. 예를 들어:

내 회로도에 3.3 V LDO 레귤레이터 서브회로를 추가하고 ERC를 실행해 줘.

응답은 배치한 부품 — 레귤레이터, 입력 및 출력 커패시터 — 의 이름을 말하고 모델이 아닌 kicad-cli에서 나온 ERC 결과를 담아야 합니다. KiCAD에서 회로도를 열어 보세요: 심볼이 있습니다.

설치 자체를 확인하려면 언제든지: 프로젝트를 열고(KiCAD의 PCB 편집기는 프로젝트 없이는 열리지 않습니다), PCB Editor → Tools → External Plugins에서 Konnect가 보여야 합니다.

아직 하지 못하는 것

• PCB 도구는 실행 중인 KiCAD가 필요하며 API가 켜져 있고 보드가 열려 있어야 합니다. 헤드리스 PCB 경로는 없습니다 — pcbnew에는 그런 것이 없습니다.

• macOS 바이너리는 서명되거나 공증되지 않았습니다. Gatekeeper가 첫 실행 시 차단합니다. macOS 섹션에 정확한 xattr 명령이 있습니다.

• Linux는 컴파일되고 CI를 통과하지만 실행 중인 KiCAD에 대한 플랫폼별 QA는 없습니다.

• 심볼과 풋프린트는 배치만 되고 작성되지는 않습니다. Konnect는 기존 라이브러리 부품을 검색하고 사용합니다. 새 부품 생성은 로드맵에 있습니다.

다섯 단계 중 어느 하나라도 작동하지 않았다면, 그것이 보고할 가치가 있는 것입니다: 첫 실행 보고서를 제출하세요. 약 2분이 걸리며, 유지관리자의 머신이 아닌 다른 머신에서 이 모든 것이 측정되는 유일한 방법입니다.

Konnect가 존재하는 이유

Konnect는 KiCAD-MCP-Server의 후속작입니다. AI 기반 PCB 설계가 작동한다는 것을 증명한 Python/TypeScript 프로젝트였고, 그 과정에서 그 아키텍처가 정확히 어디에서 한계에 부딪히는지 보여주었습니다. Konnect는 이러한 특정 문제들을 해결하기 위해 만들어졌습니다:

호출 경로가 너무 길었습니다. 원래 서버에서 단일 도구 호출은 TypeScript, 스키마 검증, 생성된 Python 하위 프로세스, stdin/stdout을 통한 JSON, 명령 라우터, 그리고 마지막으로 SWIG 생성 C++ 프록시 객체를 거쳐야 보드에 닿았습니다. 이는 네 개의 언어 및 직렬화 경계로, 각각 고유한 실패 모드가 있습니다 — 하위 프로세스 수명주기 관리, KiCAD가 스트림에 흘려보내는 경고를 걸러내는 stdout 파싱, 청크 JSON 재조립. Konnect에서 도구 호출은 함수 호출입니다. 하나의 프로세스, 하나의 언어, 배관 없음.

의존성 표면이 엄청났습니다. 원래 버전을 실행하려면 Node.js와 npm 트리, Python과 pip 패키지, wxPython, kicad-skip, 그리고 KiCAD의 SWIG 바인딩을 유지해야 했습니다 — 두 개의 패키지 생태계에 바인딩 레이어까지, 그 각각이 설치를 망가뜨릴 수 있는 움직이는 표적이었습니다. Konnect는 하나의 바이너리입니다 — Windows에서 24 MB, 인터프리터 없음, 패키지 트리 없음. 함께 설치할 것도, 버전을 맞출 것도 없습니다.

SWIG는 막다른 길입니다. 원래 버전의 PCB 백엔드는 KiCAD의 SWIG Python 바인딩에 의존하는데, KiCAD는 이를 IPC API로 대체하고 있습니다. SWIG는 또한 실제 운영상의 흉터를 지녔습니다: 백엔드를 세그폴트시킬 수 있는 영역 채우기 호출, 프록시 객체 비교 버그, 그리고 세션 중에 백엔드를 조용히 바꿔치기할 수 있는 폴백 경로. Konnect는 공식 IPC API (NNG 위의 protobuf)를 통해 KiCAD 10과 통신합니다 — KiCAD가 투자하고 있는 인터페이스 — KiCAD 자체의 실행 취소/다시 실행과 통합되는 실시간 보드 편집을 제공합니다.

회로도 편집은 파일을 손상시켜서는 안 됩니다. Konnect는 자체 S-표현식 엔진으로 .kicad_sch 파일을 편집하며 원자적 쓰기(쓰기, fsync, 이름 변경), UUID 보존, 라운드트립 테스트를 갖추고 있습니다 — 알려진 공백이 있는 타사 회로도 라이브러리도, 텍스트 조작 우회도 없습니다.

컨텍스트 경제성은 기능입니다. 전체 카탈로그 — 모든 툴셋이 로드되면 215개 도구 — 를 제공하는 것은 모든 목록에서 33K 토큰의 컨텍스트를 소비합니다. Konnect의 라우터는 21개 도구 / 2.8K 토큰의 스타터 키트로 시작하며 모델이 온디맨드로 툴셋을 가져오거나, 카탈로그를 완전히 건너뛰고 게이트웨이(kicad_describe / kicad_invoke)를 통해 도구를 호출할 수 있습니다. 이 게이트웨이는 tools/list를 전혀 변경하지 않습니다 — 또한 내장 관찰 가능성(get_recent_calls, server_stats, JSONL 호출 로그)을 통해 모델이 자체 도구 실패를 진단할 수 있습니다. 이 수치는 추정이 아니라 측정된 것입니다: docs/benchmark.md를 참조하세요.

결과는 더 작고, 설치가 더 빠르며, KiCAD가 나아가는 방향과 일치하고, 실험이 아닌 프로덕션 사용을 위해 만들어졌습니다. 원래 프로젝트는 계속 열려 있고, 유지관리되며, 유용합니다 — 아래 비교를 참조하세요.

하는 일

변경 사항을 설명하고 수동으로 적용하는 대신, AI가 프로젝트에서 직접 작업합니다:

• 회로도 부품 배치 및 배선 — 저항, IC, 커넥터 추가; 핀 이름으로 서로 배선

• PCB 레이아웃 — KiCAD의 IPC API를 통해 실시간으로 풋프린트 배치, 이동, 회전, 라우팅, 완전한 실행 취소/다시 실행 통합

• 설계 검사 실행 — ERC, DRC, 연결성 검증, 디커플링 감사, 전원 레일 검토, BOM 상태 점검

• 제조 파일 내보내기 — Gerber, 드릴, BOM, 픽앤플레이스, 3D 모델, PDF

• JLCPCB 부품 검색 — 로컬 250만 부품 카탈로그에서 재고 부품을 찾고 대안 제안

• 참조 회로에서 시작 — USB-C, LDO, 벅 컨버터, STM32, I2C, LED 템플릿(검증된 부품 값 포함)

• 실시간으로 지켜보기 — AI가 편집할 때 자동으로 새로고침되는 라이브 회로도 뷰어

전체 도구 카탈로그는 tool-directory.md에 문서화되어 있습니다.

작동 방식

설치

KiCAD 플러그인 관리자에서(권장)

1. Releases에서 OS에 맞는 패키지를 다운로드하세요: konnect-pcm-v<version>-windows.zip, -macos.zip, 또는 -linux.zip. 각각 해당 플랫폼의 서버 바이너리가 포함되어 있습니다 — macOS 패키지는 유니버설 빌드이므로 한 번의 다운로드로 Apple Silicon과 Intel을 모두 지원합니다. (konnect-pcm-* 자산은 KiCAD 플러그인 패키지이고, 다른 아카이브는 독립 실행형 서버 바이너리입니다.)

2. KiCAD 10을 열고 플러그인 및 콘텐츠 관리자로 이동합니다.

3. 파일에서 설치를 클릭하고 zip 파일을 선택합니다. 선택 즉시 설치가 진행됩니다 — 보류 중인 변경 사항 적용은 회색으로 유지되며, 확인할 다른 항목은 없습니다.

4. KiCAD를 다시 시작합니다.

5. KiCAD API를 활성화합니다: 기본 설정 → 플러그인 → KiCad API 활성화를 선택한 후 KiCAD를 다시 시작합니다. 기본적으로 꺼져 있으며, 모든 PCB 도구가 필요로 합니다.

확인: 프로젝트를 열거나 생성한 후(프로젝트가 없으면 KiCAD의 PCB 편집기가 열리지 않습니다) PCB 편집기 → 도구 → 외부 플러그인으로 이동하면 Konnect가 표시되어야 합니다.

소스에서 빌드

# protoc is required (protobuf code generation), and cmake (the nng crate
# compiles the NNG C library with it).
# Windows: choco install protoc cmake
# macOS:   brew install protobuf cmake
# Linux:   apt install protobuf-compiler cmake
cargo build --release -p konnect

macOS

Releases 페이지에는 Apple Silicon(aarch64-apple-darwin) 및 Intel(x86_64-apple-darwin)용 독립 실행형 서버 바이너리가 제공됩니다. 아직 코드 서명이 되어 있지 않으므로 브라우저를 통해 다운로드한 경우 첫 실행 전에 격리 플래그를 해제하세요:

tar xzf konnect-v*-aarch64-apple-darwin.tar.gz
xattr -d com.apple.quarantine ./konnect   # only needed for browser downloads
./konnect --help

또는 위와 같이 소스에서 빌드합니다(Apple Silicon에서 검증됨; 동일한 target/release/konnect 바이너리가 MCP 서버입니다).

macOS의 KiCAD는 도구를 앱 번들 내부에 보관하며 PATH에 포함되지 않습니다. v1.1.1은 표준 앱 번들을 검색하고 KiCAD의 기본 IPC 주소를 자동으로 사용합니다. 특이하거나 이름이 변경된 설치의 경우에만 ~/Library/Application Support/konnect/config.toml에서 명시적으로 재정의해야 합니다:

kicad_cli = "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"
kicad_binary = "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad"
# Optional override; the default is ipc:///tmp/kicad/api.sock.
ipc_address = "ipc:///tmp/kicad/api.sock"

Claude Desktop의 구성 파일은 ~/Library/Application Support/Claude/claude_desktop_config.json에 있습니다:

{
  "mcpServers": {
    "konnect": {
      "command": "/path/to/konnect"
    }
  }
}

Claude Code의 경우 프로젝트 루트의 .mcp.json에 동일한 스니펫을 넣으세요.

macOS용 PCM 패키지(konnect-pcm-v<version>-macos.zip)에는 유니버설 서버 바이너리가 포함되어 있어 한 번의 다운로드로 두 아키텍처를 모두 지원합니다. 회로도 뷰어는 macOS에서 컴파일 및 실행되지만(Tauri 2는 시스템 WKWebView를 사용 — WebView2는 Windows 전용 요구 사항입니다) 아직 Windows 빌드만큼 테스트되지는 않았습니다.

Claude Desktop으로 설정

PCM 설치 후 서버 바이너리는 KiCAD 문서 폴더에 있습니다:

C:\Users\<YOU>\Documents\KiCad\10.0\3rdparty\plugins\com_github_mixelpixx_konnect\bin\konnect.exe

%APPDATA%\Claude\claude_desktop_config.json을 편집합니다:

{
  "mcpServers": {
    "konnect": {
      "command": "C:\\Users\\<YOU>\\Documents\\KiCad\\10.0\\3rdparty\\plugins\\com_github_mixelpixx_konnect\\bin\\konnect.exe"
    }
  }
}

Claude Desktop을 다시 시작하면 Konnect 도구가 나타납니다. Claude Code의 경우 프로젝트 루트의 .mcp.json에 동일한 스니펫을 넣으세요 (examples/ 참조).

회로도 뷰어

회로도 파일이 변경될 때 자동으로 새로고침되는 독립 실행형 뷰어입니다:

schematic-viewer.exe path\to\your\root_schematic.kicad_sch

계층적 설계의 루트 시트를 지정하면 모든 하위 시트도 렌더링되며, 도구 모음에 깊이 들여쓰기된 시트 선택기가 표시됩니다. KiCAD에서 저장한 편집 내용(또는 AI가 회로도 도구를 통해 만든 편집 내용)은 변경된 시트만 다시 렌더링하고 뷰를 실시간으로 새로고침합니다 — 렌더링은 임시 폴더 스냅샷에 대해 실행되므로 뷰어가 KiCAD의 저장을 차단하지 않습니다. 클릭-드래그로 이동하고, 휠로 확대/축소하며, 0은 맞춤, R은 새로고침, 드래그 앤 드롭으로 다른 파일을 열 수 있습니다. open_schematic_viewer 도구를 통해 AI가 실행할 수도 있습니다.

WebView2 런타임(Windows 10/11에 사전 설치됨)과 kicad-cli용 KiCAD 설치가 필요합니다(자동 검색되거나 --kicad-cli <path>로 전달 가능). 기본 워크스페이스와 별도로 빌드됩니다 — 빌드 단계는 DEV.md를 참조하세요.

요구 사항

• KiCAD 10(Windows가 가장 많이 테스트된 플랫폼입니다; macOS는 릴리스 바이너리 또는 소스 빌드로 작동합니다 — 위의 macOS 섹션 참조. Linux는 CI에서 컴파일 및 테스트를 통과하지만 플랫폼별 QA는 아직 진행되지 않았습니다. 둘 다 로드맵에 추적되어 있습니다)

• kicad-cli(KiCAD에 포함 — 내보내기, ERC, DRC에 사용). KiCAD 설치 프로그램이 PATH에 추가하지 않으므로 서버가 일반적인 설치 위치를 검색하며, 다른 위치에 있는 경우 명시적으로 지정할 수 있습니다

• PCB 도구의 경우: 대상 보드가 열린 상태로 KiCAD가 실행 중이어야 하며, KiCAD API가 켜져 있어야 합니다 — 기본 설정 → 플러그인 → KiCad API 활성화, 기본적으로 꺼져 있습니다

라이선스: 소규모 사용자에게 무료

Konnect는 GNU AGPL-3.0 라이선스로 제공됩니다.

취미 사용자, 학생, 프리랜서 또는 오픈소스 프로젝트라면: 아무 조건 없이 자유롭게 사용하세요. 보드를 설계하고, 출시하고, 판매하세요.

기업이라면: AGPL은 Konnect를 기반으로 하거나 Konnect를 사용하여 구축한 모든 것(네트워크를 통해 제공되는 소프트웨어 포함)을 동일한 라이선스로 오픈소스화할 것을 요구합니다. 이것이 적합하지 않다면 상용 라이선스가 제공됩니다: COMMERCIAL.md를 참조하세요.

KiCAD-MCP-Server와의 관계

원래의 Python/TypeScript 프로젝트는 완전히 오픈(MIT) 상태로 유지 관리되고 있습니다. Konnect는 새로운 개발이 이루어지는 곳입니다 — 검증된 아키텍처를 프로덕션용으로 재구축했습니다:

문제 해결

플러그인이 KiCAD에 표시되지 않음 — 플러그인 및 콘텐츠 관리자를 통해 설치하고(수동 복사 아님) KiCAD를 다시 시작하세요. 항목은 PCB 편집기의 도구 → 외부 플러그인 아래에 있으며, 프로젝트가 열릴 때까지 PCB 편집기는 전혀 열리지 않습니다.

PCB 도구가 "IPC 연결 실패"를 반환 — 두 가지 별개의 조건이 모두 충족되어야 합니다: 기본 설정 → 플러그인 → KiCad API 활성화가 체크되어 있고(KiCAD는 기본적으로 꺼짐 상태로 제공됨) KiCAD가 보드 파일을 연 상태로 실행 중이어야 합니다. 다시 시작한 후 API 페이지에 Listening on ipc://…로 표시되어야 합니다. docs/TROUBLESHOOTING.md에서 두 가지를 모두 자세히 설명합니다.

"kicad-cli를 실행하지 못했습니다" — 서버는 다음 순서로 kicad-cli를 찾습니다: 설정한 경우 구성의 kicad_cli 값, 그 다음 PATH, 그 다음 알려진 설치 접두사(%LOCALAPPDATA%\Programs\KiCad\<ver>\bin 포함 — KiCAD 설치 프로그램이 사용자별 설치를 넣는 위치), 그 다음 Windows 레지스트리. 시작 시 어느 것이 응답했는지 로그에 기록합니다. 어느 것도 응답하지 않으면 — 특이한 설치 위치, 휴대용 복사본 — 플러그인 설정 대화상자 또는 구성 파일에서 kicad_cli를 명시적으로 설정하세요.

검증기가 0건 대신 오류를 보고 — 이는 의도된 것입니다. 실행할 수 없는 검사는 통과한 검사로 보고되지 않습니다.

지원

• 처음 사용해 보셨나요? 첫 실행 보고서 제출 — 질문 6개, 대부분 한 번의 클릭입니다. 포기한 사람의 보고서는 성공한 사람의 보고서보다 더 가치 있습니다. 결과는 docs/adoption.md에 집계됩니다.

• 버그 및 기능 요청: GitHub Issues

• 설치 또는 IPC 소켓 문제: docs/TROUBLESHOOTING.md

• 로드맵: ROADMAP.md

• 기여: CONTRIBUTING.md

텔레메트리 없음. Konnect는 어떤 것도, 어디에도, 절대 보고하지 않습니다. 다른 사람의 컴퓨터에서 어떻게 동작하는지에 대해 알려진 모든 것은 누군가가 기록하기로 선택한 것에서 비롯되었습니다. 설계 파일을 편집하는 도구는 외부로 통신하지 않음으로써 신뢰를 얻습니다.