kicad-mcp-pro

KiCad MCP Pro는 KiCad EDA 워크플로우를 위한 Model Context Protocol 서버입니다. 회로도, PCB, 검증, DFM 및 제조 내보내기 자동화를 위한 도구, 리소스 및 프롬프트를 제공합니다.

서버는 이제 제한된 default 프로필로 시작됩니다: 전체 377개 도구 전문가 카탈로그 대신 24개의 읽기 전용 검토 도구입니다. 제어된 편집을 위해 쓰기 모드로 build를 사용하고, 사람이 승인하는 핸드오프를 위해 제조 모드로 release를 사용하며, 고급 신뢰 클라이언트에만 expert/full을 사용하세요. docs/agents/progressive-disclosure.md를 참조하세요.

원격 측정 및 오류 보고는 기본적으로 비활성화되어 있습니다. 옵트인 OpenTelemetry 구성은 docs/configuration.md에 문서화되어 있으며, 개인정보 보호 규칙은 docs/privacy.md에 문서화되어 있습니다.

범위 및 정직성

KiCad MCP Pro는 전문가용 1차 설계 및 검토 보조 도구이며, 자동 승인 권한이 아닙니다. ERC/DRC 및 내보내기 파이프라인은 KiCad 자체 엔진을 구동합니다. 신호 무결성, 전원 무결성, EMC 및 열 도구는 1차 폐쇄형 추정치(일반적으로 ~5–10% 정확도)입니다 — 빠른 1차 검토를 위한 것이며, 2D/3D 필드 솔버, EM/FEA 시뮬레이션 또는 공식 승인을 대체하지 않습니다. 실시간 부품 소싱은 기본적으로 JLCPCB 공개 카탈로그를 사용합니다. Nexar, DigiKey 및 Mouser는 해당 API 자격 증명이 구성된 경우에만 사용할 수 있습니다. 서버가 KiCad의 프로그래밍 가능한 표면 중 어느 정도를 구동하는지는 기능 패리티 매트릭스에서 공개적으로 추적됩니다.

Related MCP server: KiCad MCP Server

프로젝트 식별 정보

빠른 시작

데스크톱 앱

GitHub 릴리스 페이지에서 최신 설치 프로그램을 다운로드하세요. Tauri 데스크톱 앱은 Python 대시보드 서버를 자동으로 시작하고 http://127.0.0.1:3334/ui에서 GUI를 엽니다. 데스크톱 릴리스는 사용 전에 일치하는 정확한 백엔드 버전을 실행하고 데스크톱 호환성 핸드셰이크를 확인합니다. 자세한 내용은 설치를 참조하세요.

CLI

uvx kicad-mcp-pro init
uvx kicad-mcp-pro tray
uvx kicad-mcp-pro dashboard --open
uvx kicad-mcp-pro --transport streamable-http --port 3334

웹 대시보드

uvx kicad-mcp-pro dashboard --host 127.0.0.1 --port 3334 --open
# http://127.0.0.1:3334/ui

문서

문서는 설정부터 운영까지 구성되어 있습니다:

1. 설치

2. 클라이언트 구성

3. 런타임 구성

4. 도구 참조

5. 워크플로우

6. 릴리스 프로세스

7. 보안 및 개인정보 보호

8. KiCad 기능 패리티 — 이 서버가 KiCad의 프로그래밍 가능한 표면 중 얼마나 많은 부분을 구동하는지

9. 오류 코드 카탈로그 — 안정적인 오류 코드, 재시도 클래스 및 복구

10. 작업 지시 감사 — 강화 작업 지시의 현재 상태

kicad_capability_parity() 도구는 워크플로우 도메인별로 이 서버가 구동할 수 있는 KiCad의 프로그래밍 방식으로 접근 가능한 표면의 비율(현재 76.3%)을 보고하며, KiCad가 헤드리스 API를 제공하지 않는 gui-only-no-api 항목과 진정한 gap을 구분합니다.

게시된 문서 사이트는 다음에서 확인할 수 있습니다: https://oaslananka.github.io/kicad-mcp-pro/.

전송 방식

KiCad MCP Pro는 stdio 및 Streamable HTTP를 지원합니다. Streamable HTTP는 기본적으로 /mcp에서 제공되며 KICAD_MCP_MOUNT_PATH로 이동할 수 있습니다.

uvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334

Streamable HTTP 클라이언트는 다음을 전송해야 합니다:

• Accept: application/json, text/event-stream

• Content-Type: application/json

• 초기화 후 MCP-Protocol-Version: 2025-11-25

• KICAD_MCP_STATEFUL_HTTP=1인 경우 후속 요청에 MCP-Session-Id

기본적으로 Streamable HTTP는 상태 비저장이므로 ChatGPT 스타일 커넥터가 세션 헤더 주입 프록시 없이 tools/list를 초기화하고 호출할 수 있습니다. initialize 후 세션 ID를 요구하려면 KICAD_MCP_STATEFUL_HTTP=1을 설정하세요.

더 이상 사용되지 않는 HTTP+SSE 폴백 경로는 기본적으로 비활성화되어 있습니다. Streamable HTTP를 사용할 수 없는 이전 클라이언트에 대해서만 KICAD_MCP_LEGACY_SSE=1을 설정하세요.

설치

게시된 패키지:

uvx kicad-mcp-pro --help
npx kicad-mcp-pro --help

지원되는 Linux 호스트에서 새 소스 체크아웃:

./scripts/bootstrap-dev.sh
source .dev-env.sh
pnpm run dev:doctor -- --ci

저장소 부트스트랩은 체크섬이 고정된 Python, uv/uvx, Node.js, pnpm, Task 및 Rust 도구를 무시된 체크아웃 로컬 루트에 설치하고 고정된 종속성 설치를 수행합니다. 전역 도구 디렉토리를 수정하지 않습니다. --core-only, --check, 정리, 업그레이드 및 KiCad 기능 모드에 대한 자세한 내용은 재현 가능한 부트스트랩 가이드를 참조하세요.

패키지 메타데이터

표준 메타데이터 입력은 패키지 버전 및 저장소 ID를 위한 pyproject.toml과 KiCad 및 MCP 지원 정책을 위한 compatibility.yaml입니다. server.json은 생성된 레지스트리 매니페스트입니다. pnpm run metadata:sync는 공개 표면을 렌더링하고, pnpm run metadata:check는 CI 및 릴리스 검증에서 이를 확인합니다.

사용법

CLI 명령을 확인하려면 kicad-mcp-pro --help를 사용하고, MCP 클라이언트를 구성하려면 docs/client-configuration.md를 참조하세요. 생성된 도구 카탈로그는 docs/tools-reference.generated.md에서 확인할 수 있습니다.

에이전트 플러그인 및 스킬

이 저장소는 KiCad MCP Pro를 위한 제품 수준의 에이전트 플러그인 및 KiCad 관련 스킬을 소유합니다. 중앙 agent-tools 저장소는 이 플러그인을 카탈로그화해야 하지만, 매니페스트 및 워크플로우 지침은 실제 MCP 서버 도구와 동기화된 상태를 유지하기 위해 여기에 있습니다.

에이전트 설정

KiCad MCP Pro는 게시된 Python 패키지, npm 래퍼 또는 server.json에 선언된 컨테이너 메타데이터로 실행할 수 있습니다. 일반적인 로컬 시작 방법은 다음과 같습니다:

uvx kicad-mcp-pro --transport stdio
uvx kicad-mcp-pro --transport streamable-http --host 127.0.0.1 --port 3334
npx kicad-mcp-pro --help

소스 체크아웃의 경우, 플러그인 변경 사항을 게시하기 전에 일반 저장소 검증 경로를 실행하세요:

corepack pnpm run metadata:check
python3 -m json.tool .claude-plugin/plugin.json >/dev/null

검증 워크플로우

이 플러그인을 agent-tools에서 활성 상태로 등록하기 전에, 최소한 하나의 호환 에이전트 런타임이 다음을 수행할 수 있는지 확인하세요:

1. .claude-plugin/plugin.json을 발견할 수 있어야 합니다.

2. stdio 또는 Streamable HTTP를 통해 kicad-mcp-pro를 실행하거나 연결할 수 있어야 합니다.

3. kicad_get_server_info 또는 kicad_get_project_info를 호출할 수 있어야 합니다.

4. skills/에서 스킬을 로드하고 누락된 도구를 참조하지 않고 워크플로우를 따를 수 있어야 합니다.

5. ERC, DRC, DFM, 내보내기 아티팩트, 가정, 그리고 인간 검토 요구 사항을 별도로 보고해야 합니다.

KiCad MCP Pro는 엔지니어링 어시스턴트이지 자율 제조 승인 권한이 아닙니다. 생성된 PCB 및 제조 출력물은 제조 또는 조립 전에 자격을 갖춘 인간 검토가 필요합니다.

개발

새로운 기여자는 ARCHITECTURE.md를 먼저 읽어야 합니다. 이 문서는 다섯 개의 계층(전송 → MCP 프로토콜 → 오케스트레이션 → KiCad 어댑터 seam → 순수 도메인)을 매핑하고 새 도구를 추가하는 방법을 정확히 보여줍니다. 런타임 모델 및 품질 게이트 스택은 docs/development/architecture.md에 문서화되어 있습니다.

이 프로젝트는 일반적인 개발 명령에 Taskfile.yml을 사용합니다. 저장소를 클론한 후:

task install     # Install all dependencies (pnpm + uv)
task verify      # Run the local quality gate: lint → format → typecheck → test → build
task test        # Run unit tests only
task lint        # Run lint and metadata checks
task format      # Auto-format the codebase
task typecheck   # Run strict static type checking
task build       # Build release artifacts
task ci          # Run the local equivalent of the full CI pipeline
task hooks       # Install local git hooks

모든 변경 사항은 풀 리퀘스트를 열기 전에 task verify를 통과해야 합니다.

기여

풀 리퀘스트를 열기 전에 CONTRIBUTING.md를 읽으세요. 모든 변경 사항은 저장소의 형식, 린트, 타입 검사, 테스트, 워크플로우, 보안 및 패키지 메타데이터 게이트를 통과해야 합니다.

이 소프트웨어 인용

연구 또는 기술 간행물에서 KiCad MCP Pro를 사용하는 경우, DOI(전체 메타데이터는 CITATION.cff 참조)를 통해 보관된 릴리스를 인용하세요:

@software{aslan_kicad_mcp_pro,
  author  = {Aslan, Osman},
  title   = {KiCad MCP Pro},
  license = {MIT},
  url     = {https://github.com/oaslananka/kicad-mcp-pro},
  doi     = {10.5281/zenodo.21283791}
}

모든 GitHub 릴리스는 이 개념 DOI 하에 Zenodo에 보관되며, 이는 항상 최신 버전으로 확인됩니다.

라이선스

KiCad MCP Pro는 MIT 라이선스에 따라 사용할 수 있습니다.