MochiuWiki : SUSE, EC, PCB

MCPサーバ - KiCAD

概要

KiCad MCPサーバは、電子回路設計ソフトウェア KiCadをMCP (Model Context Protocol) 経由でAIアシスタントに接続するサーバである。
2026年7月時点では、KiCad 10.0がリリースされており、実装の対応範囲と保守状態を確認して選択する必要がある。

主要な6つのMCPサーバは、以下の通りである。

  • lamaalrajih/kicad-mcp
    FastMCPとSWIGの軽量なPython実装である。
    KiCad 9.0以降向けだが、2025年10月以降は開発停止状態である。
  • mixelpixx/KiCAD-MCP-Server
    PythonとTypeScriptの活発なハイブリッド実装である。
    v2.3.1で122ツール、16カテゴリ、KiCad 10対応を提供する。
  • Seeed-Studio/kicad-mcp-server
    回路図、PCB、ネットリストの分析と検証を中心にした実装である。
  • oaslananka/kicad-mcp-pro
    stdioとStreamable HTTP、uvx、npx、Tauriを組み合わせた統合型実装である。
  • belaszalontai/kipilot-mcp
    KiCad 10の公式kicad-python IPCバインディングだけを利用するPCB中心の実装である。
  • mixelpixx/Konnect
    KiCad 10専用、v0.2.0 BETAのRust製スタンドアロンMCPサーバである。


MCPの安定仕様は2025年6月18日であり、JSON-RPC 2.0、MCPの基本プロトコル、サーバ機能の順に構成される。
ツール、リソース、プロンプトを通じて、AIから設計情報の参照、検証、限定的な変更を行える。

KiCadのファイルは設計資産であるため、変更を許可する前にバックアップ、パス制限、利用者の承認を設定する。

STDIOでは標準出力をログに使用せず、ログは標準エラー出力へ送る。


MCPサーバの比較

下表は、2026年7月時点で比較対象として整理した従来の5サーバの比較である。Konnectは後述のサーバ6で扱う。
Starsとコミット日は調査時点の値であり、将来変化する。

KiCAD MCPサーバの比較
項目 lamaalrajih mixelpixx Seeed-Studio oaslananka belaszalontai
リポジトリ kicad-mcp KiCAD-MCP-Server kicad-mcp-server kicad-mcp-pro kipilot-mcp
Stars 487 1,560 65 28 3
言語 Python 100% Python 84.3% + TypeScript 14% Python + Jinja Python主体 + TypeScript/JS/HTML/Rust Python 100%
ライセンス MIT MIT MIT MIT README記載なし
KiCad対応 9.0+ 9.0+ / 10.0 8.0+、9/10推奨 9.x / 10.x 10.xのみ
ツール数 基本セット 122 25 プロファイルで可変 読み取り・ガード付き変更
最新リリース なし v2.3.1 なし v3.25.0 v0.1.1
リリース日 開発停止 2026-07-06 2026-05-22コミット 2026-07-10 2026-05-14
主な接続 STDIO STDIO STDIO STDIO / Streamable HTTP STDIO
主用途 基本PCB操作 総合設計 分析・検証 総合設計・解析 KiCad 10 PCB検査



MCPサーバの選択

MCPサーバの選択は、KiCadのバージョン、変更を許可する範囲、クライアントの接続方式で決める。

ユースケース別の選択マトリクス
ユースケース 第一候補 理由 注意点
KiCad 10で総合操作 mixelpixx/KiCAD-MCP-Server 122ツールとハイブリッドバックエンド 開発版機能の確認が必要
KiCad 10でPCBを安全に検査 belaszalontai/kipilot-mcp 公式IPC、変更は初期状態で無効 KiCad GUIが必要
解析と検証を優先 Seeed-Studio/kicad-mcp-server 分析カテゴリが明確 KiCadバンドルPython推奨
リモートまたは複数クライアント oaslananka/kicad-mcp-pro Streamable HTTP対応 認証とポート保護が必要
KiCad 9の既存環境 lamaalrajih/kicad-mcp 導入が簡単でFastMCP中心 2025-10以降開発停止


lamaalrajih/kicad-mcpを選択する場合

  • 基本的なPCB操作のみが必要な場合
  • シンプルなセットアップを好む場合
  • Python開発環境に精通している場合
  • 既存のFastMCPベースのツールを統合したい場合
  • KiCad 9.0を固定して運用できる場合


mixelpixx/KiCAD-MCP-Serverを選択する場合

  • 包括的なツールセットが必要な場合
  • 回路図操作機能が必要な場合
  • リアルタイムUI同期を使用したい場合
  • Windows環境での使用を想定している場合
  • JLCPCB、Freerouting、3Dモデルを1つにまとめたい場合
  • KiCad 10とKiCad 9の両方を扱いたい場合


Seeed-Studio/kicad-mcp-serverを選択する場合

  • 設計レビュー、ネットリスト検査、検証を中心にしたい場合
  • KiCadバンドルPythonで完全なpcbnew分析を行える場合
  • 回路図とPCBのコード生成を分析処理と組み合わせたい場合


oaslananka/kicad-mcp-proを選択する場合

  • Streamable HTTPでリモート接続したい場合
  • TauriのGUIとPythonダッシュボードを使いたい場合
  • BOM、DFM、製造レビュー、1次近似の解析をまとめたい場合


belaszalontai/kipilot-mcpを選択する場合

  • KiCad 10専用環境で公式IPCだけを使いたい場合
  • まず読み取りを行い、変更は明示的に許可したい場合
  • PCBのアウトライン、ネット、パッド、トラック、ゾーンを検査したい場合



KiCAD 10の新機能とMCPへの影響

KiCad 10.0.0は、2026年3月に公開された。

MCPサーバを選択する場合は、新しいファイル形式とIPC APIの対応範囲を分けて考える必要がある。

設計機能の変更

  • PCB Design Blocks
    回路図とPCBの設計ブロックをライブラリ化できる。MCPでは再利用可能な設計単位の検索やレビューに影響する。
  • ピン交換とゲート交換
    回路図とPCBの前方・後方アノテーションを伴う交換を扱える。
  • グラフィカルDRC
    カスタムデザインルールをGUIで作成でき、従来のCustom Rules言語と互換性がある。
  • タイムドメイン制約
    長さだけでなく時間領域の制約で配線を調整できる。
  • Allegro、PADS、gEDA / Leptonインポーター
    外部設計の取り込み後にMCPで解析、検証する流れを作れる。


ファイル形式とライブラリ

KiCad 10では、回路図関連のフォーマットバージョンが 20260101 になった。

派生シンボルライブラリは .kicad_symdir にシャーディングされる。
この変更を認識しないサーバでは、シンボル検索や回路図解析が失敗する。

IPC APIの範囲

IPC APIはKiCad 9から継続して、KiCad 10で拡張と安定化が進んだ。

PCBエディタのIPC APIは利用できるが、回路図エディタのIPC APIはまだ開発中で利用できない。

IPC APIは稼働中のKiCad GUIインスタンスとの通信が必要である。
ヘッドレス対応は、KiCad 11で予定されている。

プロットとエクスポートはIPC APIの範囲外であるため、必要に応じて kicad-cli を使用する。

MCPへの実務上の影響

  • 読み取り専用レビューは、KiCad 10の新形式を解釈できるサーバを使用する。
  • 回路図変更はIPCだけに依存せず、SWIGまたは回路図専用実装の対応範囲を確認する。
  • エクスポート処理はIPCツールと kicad-cli の役割を分離する。
  • 変更前にプロジェクトを複製し、AIのツール呼び出しを承認制にする。



サーバ1 : lamaalrajih/kicad-mcp

概要

lamaalrajih/kicad-mcpは、PythonとFastMCPを使用したシンプルなKiCAD MCPサーバの実装である。
基本的なPCB設計操作、デザインルールチェック、製造データの出力等の機能を提供する。

以下の例では、PythonとFastMCPを使用したKiCAD MCPサーバの基本構造を示している。

 from fastmcp import FastMCP
 import pcbnew
 import os
 
 mcp = FastMCP("KiCAD MCP Server")
 
 @mcp.tool()
 def get_board_info(kicad_pcb_path: str) -> dict:
    """KiCAD PCBファイルから基板情報を取得する"""
    try:
       board = pcbnew.LoadBoard(kicad_pcb_path)
 
       info = {
          "board_name": os.path.basename(kicad_pcb_path),
          "num_tracks": board.GetTracks().GetCount(),
          "num_modules": len(list(board.GetFootprints())),
          "board_thickness": board.GetDesignSettings().GetBoardThickness(),
       }
 
       return info
    except Exception as e:
       return {"error": str(e)}
 
 @mcp.tool()
 def run_drc(kicad_pcb_path: str) -> str:
    """Design Rule Checkを実行する"""
    try:
       board = pcbnew.LoadBoard(kicad_pcb_path)
       # DRCの実装
       return "DRC実行完了"
    except Exception as e:
       return f"エラー: {str(e)}"
 
 if __name__ == "__main__":
    mcp.run()


セキュリティでは、KiCADプロジェクトファイルへのアクセス権限の管理、ファイルパスのバリデーション、適切なエラーハンドリング等を行う必要がある。
特に、パストラバーサル攻撃を防ぐため、入力されたファイルパスを適切に検証する必要がある。

パフォーマンスとスケーラビリティでは、大規模なPCBファイルの処理時間の最適化、メモリ使用量の管理が重要である。
また、複数のKiCADプロジェクトを同時に扱う場合は、適切なリソース管理を実装する必要がある。

KiCAD MCPサーバを構築・運用する場合は、以下に示す事柄に注意する。

  • KiCAD Python APIのバージョン互換性の確認
  • STDIOトランスポートでは標準出力 (stdout) にログを出力しない (JSON-RPC通信が破損する)
  • ファイル操作の実行時間を適切に管理して、タイムアウトを設定する
  • エラーハンドリングを適切に実装して、詳細なエラーメッセージを返す
  • KiCADプロジェクトファイルのバックアップを定期的に実施
  • アクセスログの監視
  • ツールのバージョン管理とドキュメントの維持


MCPサーバ環境のインストール

まず、システムの更新を行う。

# RHEL
sudo dnf update

# SUSE
sudo zypper update

# Debian
sudo apt update
sudo apt upgrade


次に、Linuxサーバに必要な基本環境をインストールする。

# RHEL
sudo dnf install curl wget git gcc-c++ make python3 python3-pip

# SUSE
sudo zypper install curl wget git gcc-c++ make python3 python3-pip

# Debian
sudo apt install curl wget git build-essential python3 python3-pip


KiCADのインストール

インストールが完了したら、KiCADのバージョンを確認する。

kicad-cli version


RHEL

RHELでは、EPELリポジトリを有効化してKiCADをインストールする。

sudo dnf install epel-release
sudo dnf install kicad kicad-doc kicad-packages3d


SUSE

SUSEでは、公式リポジトリからKiCADをインストールする。

sudo zypper install kicad kicad-doc kicad-packages3d


Debian

Debianでは、公式リポジトリからKiCADをインストールする。

sudo apt install kicad kicad-doc-ja kicad-libraries


KiCADの最新版をインストールする場合は、公式PPAを使用する。

sudo add-apt-repository ppa:kicad/kicad-9.0-releases
sudo apt update
sudo apt install kicad


Python開発環境の準備

Python仮想環境の作成

プロジェクトディレクトリを作成して、Python仮想環境を設定する。

mkdir -p ~/kicad-mcp-server
cd ~/kicad-mcp-server

python3 -m venv venv


Pythonの仮想環境をアクティベートする。

# Bash / Zshの場合
source venv/bin/activate

# Fishの場合
source venv/bin/activate.fish


必要なPythonライブラリをインストールする。

pip install fastmcp


KiCAD Python APIのインストール

KiCADのPython APIは、KiCADのインストール時に自動的にインストールされる。
Python仮想環境からKiCAD Python APIにアクセスできるように、シンボリックリンクを作成する。

まず、KiCAD Python APIの場所を確認する。

# KiCadのPythonバインディングが使用できるかどうかを確認する
# KiCadのPythonモジュール pcbnew を読み込み、Python API (実ファイル) のパスを表示する
# 続いて、GetBuildVersion() 関数で対応するKiCadのビルドバージョンを表示する

python3 -c "import pcbnew; print(pcbnew.__file__); print(pcbnew.GetBuildVersion())"

# Pythonのモジュール検索パス sys.path を取得して、その中からパス名に kicad を含むものだけを抽出する
# もし、[] (空のリスト) が表示される場合は、パス名に kicad を含む検索先がないという意味である

python3 -c "import sys; print([p for p in sys.path if 'kicad' in p.lower()])"



通常、以下に示すディレクトリにインストールされている。

  • RHEL / SUSE
    /usr/lib64/python3.x/site-packages/pcbnew.py
  • Debian
    /usr/lib/python3/dist-packages/pcbnew.py


仮想環境からアクセスできるように設定する。

# RHEL / SUSE
ln -s /usr/lib64/python3.x/site-packages/pcbnew.so venv/lib/python3.x/site-packages/

# Debian
ln -s /usr/lib/python3/dist-packages/pcbnew.py venv/lib/python3.x/site-packages/


または、~/.profileファイル等に環境変数 PYTHONPATH を設定する方法もある。

 # ~/.profileファイル等
 
 ## RHEL / SUSEの場合
 export PYTHONPATH=/usr/lib64/python3.x/site-packages:$PYTHONPATH
 
 ## Debianの場合
 export PYTHONPATH=/usr/lib/python3/dist-packages:$PYTHONPATH


KiCAD Python APIが正常にインポートできるか確認する。

python3 -c "import pcbnew; print(pcbnew.Version())"


クライアント接続設定

Claude Desktopからの接続

Claude Desktopの設定ファイルを編集する。

設定ファイルの場所は、以下の通りである。

  • Linuxの場合
    ~/.config/Claude/claude_desktop_config.json
  • Windowsの場合
    %APPDATA%\Claude\claude_desktop_config.json


設定ファイルの内容を編集する。

 {
   "mcpServers": {
     "kicad-server": {
       "command": "/home/<ユーザ名>/kicad-mcp-server/venv/bin/python",
       "args": ["/home/<ユーザ名>/kicad-mcp-server/server.py"],
       "env": {
         # RHEL / SUSEの場合
         "PYTHONPATH": "/usr/lib64/python3.x/site-packages"
 
         # Debianの場合
         "PYTHONPATH": "/usr/lib/python3/dist-packages"
       }
     }
   }
 }


環境変数 PYTHONPATH を設定することにより、KiCAD Python APIにアクセスできるようにする。

Claude Desktopを再起動して、KiCAD MCPサーバが利用可能であることを確認する。

OpenCodeからの接続

OpenCodeでは、プロジェクトルートの opencode.json または opencode.jsonc に設定を記述する。
全体設定を使用する場合は、Linuxでは ~/.config/opencode/opencode.json を使用するる。

設定はトップレベルの mcp フィールドに記述する。

設定例を以下に示す。

  • command
    実行ファイルと引数を1つの配列にまとめる。
  • environment
    環境変数を記述する。


 {
   "$schema": "https://opencode.ai/config.json",
   "mcp": {
     "kicad-server": {
       "type": "local",
       "command": [
         "/home/<ユーザ名>/kicad-mcp-server/venv/bin/python",
         "/home/<ユーザ名>/kicad-mcp-server/server.py"
       ],
       "environment": {
         "PYTHONPATH": "/usr/lib64/python3.x/site-packages"
       },
       "enabled": true
     }
   }
 }


RHEL / SUSEでは、環境変数 PYTHONPATH を使用する。
Debianでは、/usr/lib/python3/dist-packages に置き換える。

必要に応じて、cwd で作業ディレクトリを指定して、timeout で接続待ち時間を設定できる。

設定後、以下に示すコマンドでMCPサーバ一覧を確認する。

opencode mcp list


接続の詳細を確認する場合は、opencode mcp debug <サーバ名> コマンドを実行する。

詳しい仕様は、OpenCode公式MCPサーバ設定を参照すること。


設定

KiCAD MCPサーバは、環境変数 または .env ファイルを使用して設定することができる。

主要な設定オプション
環境変数 説明 例
KICAD_SEARCH_PATHS KiCADプロジェクトを検索するディレクトリ
(カンマ区切りのリスト)		 ~/pcb
~/Electronics
~/Projects
KICAD_USER_DIR デフォルトのKiCADユーザディレクトリを上書きする。 ~/Documents/KiCadProjects
KICAD_APP_PATH デフォルトのKiCADアプリケーションパスを上書きする。 /Applications/KiCad9/KiCad.app


環境設定ファイル (.envファイル) を作成する。

.env ファイルは、KiCAD MCPサーバのプロジェクトルートディレクトリに配置する。
したがって、main.py ファイル や .env.example ファイルと同じ階層、kicad-mcpディレクトリ直下に配置することが標準的である。

  • Linux 
     # .envファイル
 
 KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects
 KICAD_USER_DIR=~/Documents/KiCadProjects
 KICAD_APP_PATH=/usr/bin/kicad

  • Winodws 
     # .envファイル
 
 KICAD_SEARCH_PATHS=C:/Users/<ユーザ名>/pcb,C:/Users/<ユーザ名>/Electronics,C:/Users/<ユーザ名>/Projects
 KICAD_USER_DIR=C:/Users/<ユーザ名>/Documents/KiCadProjects
 KICAD_APP_PATH=C:/Program Files/KiCad/9.0/bin/kicad.exe


プロジェクト構造

KiCAD MCPサーバは、以下に示すモジュール構造で構成されている。

kicad-mcp/
├── README.md                       # プロジェクトドキュメント
├── main.py                         # サーバを実行するエントリーポイント
├── requirements.txt                # Python依存関係
├── .env.example                    # 環境設定の例
├── kicad_mcp/                      # メインパッケージディレクトリ
│   ├── __init__.py
│   ├── server.py                   # MCPサーバのセットアップ
│   ├── config.py                   # 設定定数と設定項目
│   ├── context.py                  # ライフサイクル管理と共有コンテキスト
│   ├── resources/                  # リソースハンドラ
│   ├── tools/                      # ツールハンドラ
│   ├── prompts/                    # プロンプトテンプレート
│   └── utils/                      # ユーティリティ関数
├── docs/                           # ドキュメント
└── tests/                          # ユニットテスト


下表に、各ディレクトリの役割を示す。

ディレクトリ 説明
kicad_mcp/resources/ KiCADプロジェクトファイル、回路図、PCBレイアウト等のリソースを処理するハンドラを格納する。
これらのハンドラは、MCPクライアントからのリソース要求に応答する。
kicad_mcp/tools/ KiCADの操作を実行するツールのハンドラを格納する。
各ツールは特定の機能 (DRCの実行、ガーバーファイルの出力等) を提供する。
kicad_mcp/prompts/ AIアシスタントが使用するプロンプトテンプレートを格納する。
これらのテンプレートは、特定のタスクに対して適切なコンテキストを提供する。
kicad_mcp/utils/ ファイル操作、パスの検証、ログ処理等の共通ユーティリティ関数を格納する。
docs/ APIドキュメント、使用例、開発ガイド等の詳細なドキュメントを格納する。
tests/ 各モジュールのユニットテストおよび統合テストを格納する。


KiCAD MCPサーバの実装

基本的なサーバ構造

KiCAD MCPサーバの基本実装を行う。

 # server.pyファイル
 
 from fastmcp import FastMCP
 import pcbnew
 import os
 from pathlib import Path
 
 mcp = FastMCP("KiCAD MCP Server")
 
 @mcp.tool()
 def load_board(kicad_pcb_path: str) -> dict:
    """KiCAD PCBファイルを読み込み、基本情報を取得する"""
    try:
       if not os.path.exists(kicad_pcb_path):
          return {"error": "ファイルが見つかりません"}
 
       if not kicad_pcb_path.endswith('.kicad_pcb'):
          return {"error": "KiCAD PCBファイルではありません"}
 
       board = pcbnew.LoadBoard(kicad_pcb_path)
 
       info = {
          "board_name": os.path.basename(kicad_pcb_path),
          "layer_count": board.GetCopperLayerCount(),
          "board_thickness": board.GetDesignSettings().GetBoardThickness() / 1000000.0,
          "track_count": board.GetTracks().GetCount(),
          "footprint_count": len(list(board.GetFootprints())),
       }
 
       return info
    except Exception as e:
       return {"error": f"PCB読み込みエラー: {str(e)}"}
 
 @mcp.tool()
 def get_footprints(kicad_pcb_path: str) -> list:
    """基板上のフットプリント一覧を取得する"""
    try:
       board = pcbnew.LoadBoard(kicad_pcb_path)
       footprints = []
 
       for footprint in board.GetFootprints():
          fp_info = {
             "reference": footprint.GetReference(),
             "value": footprint.GetValue(),
             "footprint": footprint.GetFPID().GetLibItemName().GetUniChar(),
             "layer": footprint.GetLayerName(),
          }
          footprints.append(fp_info)
 
       return footprints
    except Exception as e:
       return [{"error": str(e)}]
 
 @mcp.tool()
 def get_net_list(kicad_pcb_path: str) -> list:
    """ネットリストを取得する"""
    try:
       board = pcbnew.LoadBoard(kicad_pcb_path)
       nets = []
 
       for net in board.GetNetInfo().NetsByName():
          net_info = {
             "net_code": net[1].GetNetCode(),
             "net_name": net[1].GetNetname(),
          }
          nets.append(net_info)
 
       return nets
    except Exception as e:
       return [{"error": str(e)}]
 
 @mcp.tool()
 def run_drc(kicad_pcb_path: str) -> dict:
    """Design Rule Checkを実行する"""
    try:
       board = pcbnew.LoadBoard(kicad_pcb_path)
 
       # DRC設定の取得
       drc_settings = board.GetDesignSettings()
 
       # 簡易的なDRCチェック
       track_width = drc_settings.m_TrackMinWidth / 1000000.0
       clearance = drc_settings.m_MinClearance / 1000000.0
 
       result = {
          "min_track_width": track_width,
          "min_clearance": clearance,
          "status": "DRCチェック完了",
       }
 
       return result
    except Exception as e:
       return {"error": f"DRCエラー: {str(e)}"}
 
 @mcp.tool()
 def get_board_outline(kicad_pcb_path: str) -> dict:
    """基板外形の寸法を取得する"""
    try:
       board = pcbnew.LoadBoard(kicad_pcb_path)
       bbox = board.GetBoardEdgesBoundingBox()
 
       dimensions = {
          "width": bbox.GetWidth() / 1000000.0,
          "height": bbox.GetHeight() / 1000000.0,
          "area": (bbox.GetWidth() * bbox.GetHeight()) / 1000000000000.0,
       }
 
       return dimensions
    except Exception as e:
       return {"error": str(e)}
 
 @mcp.tool()
 def export_gerber(kicad_pcb_path: str, output_dir: str) -> str:
    """ガーバーファイルを出力する"""
    try:
       board = pcbnew.LoadBoard(kicad_pcb_path)
 
       if not os.path.exists(output_dir):
          os.makedirs(output_dir)
 
       plot_controller = pcbnew.PLOT_CONTROLLER(board)
       plot_options = plot_controller.GetPlotOptions()
 
       plot_options.SetOutputDirectory(output_dir)
       plot_options.SetPlotFrameRef(False)
       plot_options.SetLineWidth(pcbnew.FromMM(0.1))
 
       # レイヤーごとにプロット
       layers = [
          ("F.Cu", pcbnew.F_Cu, "Top Copper"),
          ("B.Cu", pcbnew.B_Cu, "Bottom Copper"),
          ("F.Mask", pcbnew.F_Mask, "Top Soldermask"),
          ("B.Mask", pcbnew.B_Mask, "Bottom Soldermask"),
          ("F.SilkS", pcbnew.F_SilkS, "Top Silkscreen"),
          ("B.SilkS", pcbnew.B_SilkS, "Bottom Silkscreen"),
          ("Edge.Cuts", pcbnew.Edge_Cuts, "Board Outline"),
       ]
 
       for layer_info in layers:
          plot_controller.SetLayer(layer_info[1])
          plot_controller.OpenPlotfile(layer_info[0], pcbnew.PLOT_FORMAT_GERBER, layer_info[2])
          plot_controller.PlotLayer()
 
       plot_controller.ClosePlot()
 
       return f"ガーバーファイルを {output_dir} に出力しました"
    except Exception as e:
       return f"エラー: {str(e)}"
 
 if __name__ == "__main__":
    mcp.run()


エラーハンドリング

本番環境では、詳細なエラーハンドリングを定義する。

 import logging
 from typing import Optional
 
 # ログ設定 (stderrに出力)
 logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[logging.StreamHandler()]
 )
 
 logger = logging.getLogger(__name__)
 
 def safe_load_board(kicad_pcb_path: str) -> Optional[pcbnew.BOARD]:
    """安全にKiCAD PCBファイルを読み込む"""
    try:
       # パスバリデーション
       path = Path(kicad_pcb_path).resolve()
 
       # パストラバーサル攻撃を防ぐ
       if '..' in str(path):
          logger.error(f"無効なパス: {kicad_pcb_path}")
          return None
 
       if not path.exists():
          logger.error(f"ファイルが存在しません: {kicad_pcb_path}")
          return None
 
       if not str(path).endswith('.kicad_pcb'):
          logger.error(f"KiCAD PCBファイルではありません: {kicad_pcb_path}")
          return None
 
       board = pcbnew.LoadBoard(str(path))
       logger.info(f"PCBファイルを読み込みました: {kicad_pcb_path}")
 
       return board
    except Exception as e:
       logger.exception(f"PCB読み込みエラー: {str(e)}")
       return None


MCP Inspectorによるテスト

MCP Inspectorを使用して、KiCAD MCPサーバのツールをテストする。

まず、MCP Inspectorをインストールする。

pip install mcp-inspector


MCP Inspectorを起動する。

mcp-inspector python server.py


Webブラウザが自動的に開いて、インスペクターのインターフェースが表示される。

テスト用のKiCADプロジェクトファイルを準備して、各ツールの動作を確認する。

  • load_board
    PCBファイルの基本情報を取得
  • get_footprints
    フットプリント一覧を取得
  • get_net_list
    ネットリスト一覧を取得
  • run_drc
    DRCチェックの実行
  • get_board_outline
    基板外形の寸法を取得
  • export_gerber
    ガーバーファイルの出力


Systemdサービスファイルの作成

KiCAD MCPサーバをシステムサービスとして常時起動させる場合、Systemdユニットファイルを作成する。

sudo vi /etc/systemd/system/kicad-mcp-server.service



 # /etc/systemd/system/kicad-mcp-server.serviceファイル
 
 [Unit]
 Description=KiCAD MCP Server
 After=network.target
 
 [Service]
 Type=simple
 User=<実行する任意のユーザ名>
 WorkingDirectory=/home/<ユーザ名>/kicad-mcp-server
 ExecStart=/home/<ユーザ名>/kicad-mcp-server/venv/bin/python server.py
 Restart=always
 RestartSec=10
 StandardOutput=journal
 StandardError=journal
 
 # 環境変数の設定
 ## Debianの場合
 Environment="PYTHONPATH=/usr/lib64/python3.x/site-packages"
 
 ## Debianの場合
 Environment="PYTHONPATH=/usr/lib/python3/dist-packages"
 
 Environment="DISPLAY=:0"
 
 [Install]
 WantedBy=multi-user.target


サービスを有効化して起動する。

sudo systemctl daemon-reload
sudo systemctl enable kicad-mcp-server
sudo systemctl start kicad-mcp-server


サービスの状態を確認する。

sudo systemctl status kicad-mcp-server


ログを確認する。

sudo journalctl -u kicad-mcp-server -f


セキュリティ設定

ファイルアクセスの制限

KiCAD MCPサーバがアクセス可能なディレクトリを制限することが推奨される。

 # 許可されたディレクトリのリスト
 ALLOWED_DIRECTORIES = [
    "/home/<ユーザ名>/kicad-projects",
    "/home/<ユーザ名>/shared-projects",
 ]
 
 def is_path_allowed(file_path: str) -> bool:
    """ファイルパスが許可されたディレクトリ内にあるか確認する"""
    try:
       resolved_path = Path(file_path).resolve()
 
       for allowed_dir in ALLOWED_DIRECTORIES:
          allowed_path = Path(allowed_dir).resolve()
          if resolved_path.is_relative_to(allowed_path):
             return True
 
       return False
    except Exception:
       return False
 
 @mcp.tool()
 def load_board_secure(kicad_pcb_path: str) -> dict:
    """セキュアなPCBファイル読み込み"""
    if not is_path_allowed(kicad_pcb_path):
       return {"error": "このファイルへのアクセスは許可されていません"}
    
    # 以降の処理


入力データのバリデーション

ツールのパラメータに対して、適切なバリデーションを行う。

 import re
 
 def validate_file_path(path: str) -> bool:
    """ファイルパスの妥当性を検証する"""
    # パストラバーサル攻撃を防ぐ
    if '..' in path:
       return False
 
    # 許可された拡張子のみ
    allowed_extensions = ['.kicad_pcb', '.kicad_pro', '.kicad_sch']
    if not any(path.endswith(ext) for ext in allowed_extensions):
       return False
 
    # 不正な文字を含まない
    if not re.match(r'^[a-zA-Z0-9._\-/]+$', path):
       return False
    
    return True


バックアップとリストア

KiCADプロジェクトのバックアップ

定期的にKiCADプロジェクトをバックアップする。

 # backup-kicad-projects.shファイル
 
 #!/usr/bin/env sh
 
 BACKUP_DIR="/var/backups/kicad-projects"
 DATE=$(date +%Y%m%d_%H%M%S)
 PROJECT_DIR="/home/<ユーザ名>/kicad-projects"
 
 # バックアップディレクトリの作成
 mkdir -p $BACKUP_DIR
 
 # プロジェクトディレクトリの圧縮
 tar -czf "$BACKUP_DIR/kicad-projects_$DATE.tar.gz" -C $(dirname $PROJECT_DIR) $(basename $PROJECT_DIR)
 
 # 30日以上前のバックアップを削除
 find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete
 
 echo "バックアップ完了: kicad-projects_$DATE.tar.gz"


バックアップスクリプトを実行可能にする。

chmod u+x backup-kicad-projects.sh


cronジョブとして設定する。

crontab -e



# 毎日午前3時にバックアップを実行
0 3 * * * /path/to/backup-kicad-projects.sh


トラブルシューティング

KiCAD Python APIがインポートできない
  • KiCADが正しくインストールされているか確認する。 
    kicad-cli version
  • 環境変数PYTHONPATH が正しく設定されているか確認する。 
    echo $PYTHONPATH
  • Python仮想環境からKiCAD Python APIへのシンボリックリンクが正しいか確認する。 
    ls -la venv/lib/python3.x/site-packages/pcbnew*


PCBファイルの読み込みに失敗する
  • ファイルパスが正しいか確認する。
  • ファイルの読み取り権限があるか確認する。 
    ls -la /path/to/file.kicad_pcb
  • KiCADのバージョンとファイルフォーマットの互換性を確認する。


Claude Desktopから接続できない
  • 設定ファイルのパスが正しいか確認する。
  • Python仮想環境のパスが正しいか確認する。
  • 環境変数 PYTHONPATH が設定されているか確認する。
  • STDIOトランスポートの場合、標準出力にログを出力していないか確認する。


ガーバーファイルの出力に失敗する
  • 出力ディレクトリの書き込み権限があるか確認する。
  • ディスク容量が十分にあるか確認する。
  • KiCADのプロットコントローラの設定を確認する。


パフォーマンス最適化

大規模PCBファイルの処理

大規模なPCBファイルを処理する場合、メモリ使用量と処理時間に注意する必要がある。

 import gc
 
 @mcp.tool()
 def process_large_board(kicad_pcb_path: str) -> dict:
    """大規模なPCBファイルを効率的に処理する"""
    try:
       board = pcbnew.LoadBoard(kicad_pcb_path)
 
       # 必要な情報のみを抽出
       result = extract_board_info(board)
 
       # ボードオブジェクトを明示的に削除
       del board
       gc.collect()
 
       return result
    except Exception as e:
       return {"error": str(e)}


キャッシングの実装

頻繁にアクセスされるデータをキャッシュすることにより、パフォーマンスを向上させる。

 from functools import lru_cache
 import hashlib
 
 def get_file_hash(file_path: str) -> str:
    """ファイルのハッシュ値を計算する"""
    with open(file_path, 'rb') as f:
       return hashlib.md5(f.read()).hexdigest()
 
 @lru_cache(maxsize=10)
 def get_cached_board_info(file_path: str, file_hash: str) -> dict:
    """キャッシュされたボード情報を取得する"""
    board = pcbnew.LoadBoard(file_path)
    # 情報を抽出
    return extract_board_info(board)
 
 @mcp.tool()
 def load_board_cached(kicad_pcb_path: str) -> dict:
    """キャッシュを使用してPCBファイルを読み込む"""
    try:
       file_hash = get_file_hash(kicad_pcb_path)
       return get_cached_board_info(kicad_pcb_path, file_hash)
    except Exception as e:
       return {"error": str(e)}


参考情報



サーバ2 : mixelpixx/KiCAD-MCP-Server

概要

mixelpixx/KiCAD-MCP-Serverは、TypeScriptとPythonのハイブリッド実装による高度なKiCAD MCPサーバである。
MCP 2025-06-18仕様に対応し、122のツールを16カテゴリに分け、包括的なエラーハンドリングとクロスプラットフォーム対応を提供する。

主要な機能
  • 122のツール
    JSON Schemaによる完全なバリデーション
  • 8のリソース
    プロジェクト状態へのリアルタイムアクセス
  • IPC API統合 (実験的)
    KiCAD 9.0のIPC APIによるリアルタイムUI同期
  • 回路図設計機能
    kicad-skipライブラリによる回路図操作
  • JLCPCB統合 (開発中)
    部品データベースとの統合
  • ハイブリッドバックエンド
    IPC APIとSWIG APIの自動切り替え


アーキテクチャ

KiCAD-MCP-Serverは、3層構造で実装されている。

  • TypeScriptサーバ層 (src/)
    MCP 2025-06-18プロトコルの実装、Pythonサブプロセスのライフサイクル管理、メッセージルーティング、ロギングとエラーリカバリ
  • Pythonインターフェース層 (python/)
    MCPメッセージハンドラ、コマンドルーティング、バックエンドの抽象化
  • KiCAD統合層
    pcbnew API (SWIG)、IPC API (kipy)、kicad-skip (回路図操作)


動作要件
  • KiCAD 9.0以降 または KiCad 10.0
    Python API (pcbnew) を含む
  • Node.js 18以上
  • Python 3.9以上
  • 必須Pythonパッケージ
    kicad-python (kipy) >= 0.5.0 (IPC API対応、オプション)
    kicad-skip >= 0.1.0
    Pillow >= 9.0.0
    cairosvg >= 2.7.0
    colorlog >= 6.7.0
    pydantic >= 2.5.0
    requests >= 2.32.5
    python-dotenv >= 1.0.0


インストール

Linux

KiCAD 9.0以降および必要な依存関係をインストールする。

# RHEL
sudo dnf install epel-release
sudo dnf install kicad kicad-doc kicad-packages3d

# SUSE
sudo zypper install kicad kicad-doc kicad-packages3d

# Debian
sudo add-apt-repository --yes ppa:kicad/kicad-9.0-releases
sudo apt update
sudo apt install kicad kicad-libraries


Node.jsをインストールする。

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# RHEL
sudo dnf install nodejs

# SUSE
sudo zypper install nodejs

# Debian
sudo apt install nodejs


KiCAD-MCP-Serverのリポジトリをクローンしてビルドする。

git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server

npm install
pip3 install -r requirements.txt
npm run build


インストールを検証する。

python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"


Windows

自動セットアップスクリプトを使用する。

git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server

.\setup-windows.ps1


このスクリプトは以下の処理を自動的に実行する。

  • KiCADのインストール検出
  • 前提条件の検証
  • 依存関係のインストール
  • プロジェクトのビルド
  • 設定ファイルの生成
  • 診断の実行


設定

Claude Desktop

Claude Desktopの設定ファイルを編集する。

設定ファイルの場所は、以下の通りである。

  • Linux
    ~/.config/Claude/claude_desktop_config.json
  • Windows
    %APPDATA%\Claude\claude_desktop_config.json


設定内容は以下の通りである。

 {
   "mcpServers": {
     "kicad": {
       "command": "node",
       "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
       "env": {
         "PATH": "/usr/bin:/usr/local/bin:/home/user/.local/bin",
         "PYTHONPATH": "/usr/lib64/python3.x/site-packages",
         "KICAD_PYTHON": "/usr/bin/python3"
       }
     }
   }
 }


プラットフォーム別の環境変数 PYTHONPATH の設定は、以下の通りである。

  • Linux (RHEL / SUSE)
    /usr/lib64/python3.x/site-packages
  • Linux (Debian)
    /usr/lib/kicad/lib/python3/dist-packages
  • Windows
    KiCad 9の場合 : C:\Program Files\KiCad\9.0\lib\python3\dist-packages
    KiCad 10の場合 : C:\Program Files\KiCad\10.0\lib\python3\dist-packages


OpenCode

OpenCodeでは、プロジェクトルートの opencode.json または opencode.jsonc にMCPサーバを設定する。
Linuxで全プロジェクトから使用する場合は、~/.config/opencode/opencode.json に設定する。

Claude Desktopとは異なり、OpenCodeではトップレベルの mcp フィールドを使用する。
実行ファイルと引数は command 配列にまとめ、環境変数は environment に記述する。

設定例を以下に示す。

 {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
       "kicad": {
          "type": "local",
          "command": [
             "node",
             "/path/to/KiCAD-MCP-Server/dist/index.js"
          ],
          "environment": {
             "PATH": "/usr/bin:/usr/local/bin:/home/user/.local/bin",
             "PYTHONPATH": "/usr/lib64/python3.x/site-packages",
             "KICAD_PYTHON": "/usr/bin/python3"
          },
          "enabled": true
       }
    }
 }


Windowsでは、command 配列の実行ファイルとパスを環境に合わせて変更する。

 {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
       "kicad": {
          "type": "local",
          "command": [
             "node",
             "C:/path/to/KiCAD-MCP-Server/dist/index.js"
          ],
          "environment": {
             "PYTHONPATH": "C:/Program Files/KiCad/10.0/lib/python3/dist-packages",
             "KICAD_PYTHON": "C:/Program Files/KiCad/10.0/bin/python.exe"
          },
          "enabled": true
       }
    }
 }


設定後、opencode mcp list コマンドを実行して、サーバが一覧に表示されることを確認する。
接続の詳細を確認する場合は、opencode mcp debug kicad コマンドを実行する。

詳しい仕様は、OpenCode公式MCPサーバ設定を参照すること。

Cline (VSCode)

Clineの設定ファイルを編集する。

  • ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json


設定内容は、Claude Desktopと同じフォーマットを使用する。

Claude Code

Claude Codeは、カレントディレクトリ内のMCPサーバを自動的に検出するため、追加の設定は不要である。

Cursor

Cursorでは、2つの方法でMCPサーバを追加できる。

  • グローバルMCPサーバとして追加する場合 (全てのプロジェクトで利用可能)
    ~/.cursor/mcp.jsonファイルを編集する。
     {
   "mcpServers": {
     "kicad": {
       "autoApprove": [],
       "disabled": false,
       "timeout": 60,
       "command": "C:\\Program Files\\nodejs\\node.exe",
       "args": ["C:/path/to/kicad-mcp/dist/index.js"],
       "env": {
          "PYTHONPATH": "C:/Program Files/KiCad/10.0/lib/python3/dist-packages",
         "DEBUG": "mcp:*"
       },
       "transportType": "stdio"
     }
   }
 }

  • プロジェクト固有のMCPサーバとして追加する場合
    プロジェクトディレクトリに .cursor/mcp.json ファイルを作成


設定後、[Cursor Settings] - [MCP]で更新ボタンを押下する。

利用可能なツール

KiCAD-MCP-Server v2.3.1は122のツールを16カテゴリに分類している。

v2.3.1の122ツール内訳
カテゴリ ツール数 内容
Project Management 5 プロジェクトの作成、読込、保存、情報管理
Board Operations 12 基板外形、レイヤー、表示、ボード属性
Component Management 16 部品配置、移動、回転、整列、属性
Routing 13 ネット、配線、ビア、差動対、ゾーン
Schematic 27 動的シンボルロードと最大10,000シンボル規模の処理
Design Rules / DRC 8 デザインルールとDRC
Export 8 ガーバー、PDF、SVG、3D、BOM等
Footprint Libraries 4 フットプリントライブラリ検索
Symbol Libraries 4 シンボルライブラリ検索
Footprint Creator 4 フットプリント生成
Symbol Creator 4 シンボル生成
Datasheet 2 データシート処理
JLCPCB Integration 5 250万以上の部品情報との統合
Freerouting Autorouter 4 Freerouting自動配線
UI Management 2 KiCad UIの状態と起動
Router / Discovery 3 ルータとサーバ探索


v2.3.1の追加機能
  • import_eagle_schematic
    Eagleの .sch 回路図をインポートする。
  • add_component_3d_model
    部品へ3Dモデルを追加する。
  • remove_component_3d_model
    部品から3Dモデルを削除する。
  • 対話型再読み込み
    Windowsでは、環境変数 KICAD_INTERACTIVE_SCHEMATIC=1 を設定する。
  • KiCad 10互換性
    kicad_symdir、レジストリ経由のインストール検出、フォーマットバージョン 20260101 に対応する。


Konnectの位置付け

Konnectは、mixelpixx/KiCAD-MCP-Serverの後継として公開されたKiCad 10専用の実装である。

詳細な導入手順、対応範囲、配布物の違いは、サーバ6 : mixelpixx/Konnectを参照する。

ツールカテゴリの概要

v2.3.1では、122のツールが16カテゴリに分類されている。

v2.1.0-alpha時点の内部インベントリでは137ツールが記録されていたが、その後のルーティング整理と統合により122に落ち着いた。
更に、未リリース部 (Unreleased) で7ツールの追加が進められている。

mixelpixx/KiCAD-MCP-Server v2.3.1 のツールカテゴリ
カテゴリ ツール数 主な内容
Project Management 5 プロジェクト作成、保存、メタデータ
Board Operations 12 ボードサイズ、外形、レイヤー、マウンティングホール、テキスト
Component Management 16 配置、移動、回転、編集、配列、整列、複製
Routing 13 トレース、ビア、ネット、ネットクラス、銅箔ポア、差動ペア
Schematic 27 回路図作成、配線、動的シンボルロード (約10,000シンボル)
Design Rules / DRC 8 DRC設定、取得、実行、違反レポート
Export 8 ガーバー、PDF、SVG、3D (STEP/VRML)、BOM
Footprint Libraries 4 フットプリントライブラリの一覧、検索、詳細取得
Symbol Libraries 4 シンボルライブラリの操作
Footprint Creator 4 カスタムフットプリント作成
Symbol Creator 4 カスタムシンボル作成
Datasheet 2 データシート関連
JLCPCB Integration 5 JLCPCB部品データベース (250万以上の部品)
Freerouting Autorouter 4 Freerouting連携 (Docker/Podman経由)
UI Management 2 KiCad UIの起動、検出
Router / Discovery 3 バックエンド探索、IPC/SWIG自動切り替え


以下に、主要カテゴリの代表的なツールを示す。

各カテゴリの全ツールはリポジトリのREADMEを参照すること。

Project Management (5ツール)
  • create_project
    新しいKiCADプロジェクトを初期化する
  • open_project
    既存のプロジェクトファイルを読み込む
  • save_project
    現在のプロジェクト状態を保存する
  • get_project_info
    プロジェクトのメタデータを取得する


Board Operations (12ツール)
  • set_board_size
    PCBの寸法を設定する
  • add_board_outline
    ボードエッジを作成する (矩形、円形、ポリゴン)
  • add_layer
    レイヤースタックにカスタムレイヤーを追加する
  • set_active_layer
    作業レイヤーを切り替える
  • get_layer_list
    全てのボードレイヤーをリストする
  • get_board_info
    ボードのプロパティを取得する
  • get_board_2d_view
    ボードのプレビュー画像を生成する
  • add_mounting_hole
    マウンティングホールを配置する
  • add_board_text
    テキスト注釈を追加する


Component Management (16ツール)
  • place_component
    フットプリントを指定して単一のコンポーネントを配置する
  • move_component
    既存のコンポーネントを再配置する
  • rotate_component
    コンポーネントを指定角度で回転する
  • delete_component
    ボードからコンポーネントを削除する
  • edit_component
    コンポーネントのプロパティを変更する
  • get_component_properties
    コンポーネントの詳細を照会する
  • get_component_list
    配置された全てのコンポーネントをリストする
  • place_component_array
    コンポーネントのグリッド/パターンを作成する
  • align_components
    複数のコンポーネントを整列する
  • duplicate_component
    既存のコンポーネントをコピーする


Routing (13ツール)
  • add_net
    電気ネットを作成する
  • route_trace
    銅箔トレースをルーティングする
  • add_via
    レイヤー遷移用のビアを配置する
  • delete_trace
    トレースを削除する
  • get_nets_list
    全てのネットをリストする
  • create_netclass
    ルール付きのネットクラスを定義する
  • add_copper_pour
    銅箔ゾーン/ポアを作成する
  • route_differential_pair
    差動信号をルーティングする


Schematic (27ツール)

v2.1.0以降に拡張された回路図機能は、約10,000のKiCadシンボルへ動的アクセスを提供する。
代表ツールを以下に示す。

  • create_schematic
    新しい回路図を初期化する
  • load_schematic
    既存の回路図を開く
  • add_schematic_component
    シンボルを配置する
  • add_schematic_wire
    コンポーネントピンを接続する
  • import_eagle_schematic
    Eagleの .sch ファイルをインポートする (v2.3.1新機能)
  • list_schematic_libraries
    シンボルライブラリをリストする
  • export_schematic_pdf
    回路図PDFをエクスポートする


Design Rules / DRC (8ツール)
  • set_design_rules
    DRCパラメータを設定する
  • get_design_rules
    現在のルールを取得する
  • run_drc
    デザインルールチェックを実行する
  • get_drc_violations
    DRCエラーレポートを取得する


Export (8ツール)
  • export_gerber
    ガーバー製造ファイルを生成する
  • export_pdf
    PDFドキュメントをエクスポートする
  • export_svg
    SVGベクターグラフィックスを作成する
  • export_3d
    3Dモデルを生成する (STEP/VRML)
  • export_bom
    部品表を作成する


Footprint Libraries / Symbol Libraries (各4ツール)
  • list_libraries
    利用可能なフットプリントライブラリをリストする
  • search_footprints
    フットプリントを検索する
  • list_library_footprints
    ライブラリ内のフットプリントをリストする
  • get_footprint_info
    フットプリントの詳細を取得する


Footprint Creator / Symbol Creator (各4ツール)

カスタムフットプリント、カスタムシンボルを作成するツール群である。

Datasheet (2ツール)

データシートの取得、参照に関するツールである。

JLCPCB Integration (5ツール)

JLCPCBの部品データベース (250万以上の部品) と直接統合し、部品検索やBOM生成を自動化する。
デュアルモードアーキテクチャにより、ローカルとリモートの両方のシンボルライブラリを検索できる。

Freerouting Autorouter (4ツール)

FreeroutingオートルータをDocker/Podman経由で呼び出し、Specctra DSN形式のラウンドトリップで自動配線を実行する。
v2.2.x系列で統合された機能である。

3Dモデル関連 (v2.3.1新機能)
  • add_component_3d_model
    コンポーネントに3Dモデルを追加する
  • remove_component_3d_model
    コンポーネントから3Dモデルを削除する


UI Management (2ツール)
  • check_kicad_ui
    KiCADが実行中かチェックする
  • launch_kicad_ui
    KiCADアプリケーションを起動する


Router / Discovery (3ツール)

バックエンドの探索、IPCとSWIGの自動切り替え、ルーティング制御を担う。

開発モードは、環境変数 KICAD_MCP_DEV=1 で有効になる。

リソース

KiCAD-MCP-Serverは、8つのリソースを提供し、プロジェクト状態への読み取り専用アクセスを提供する。

  • kicad://project/current/info
    プロジェクトのメタデータ
  • kicad://project/current/board
    ボードのプロパティ
  • kicad://project/current/components
    コンポーネントリスト (JSON形式)
  • kicad://project/current/nets
    電気ネット
  • kicad://project/current/layers
    レイヤースタック設定
  • kicad://project/current/design-rules
    現在のDRC設定
  • kicad://project/current/drc-report
    デザインルール違反
  • kicad://board/preview.png
    ボードビジュアライゼーション (PNG形式)


これらのリソースを使用することにより、AIアシスタントはツールを実行せずにプロジェクトの状態を照会できる。

使用例を以下に示す。

# 現在のコンポーネントリストを表示する
現在のコンポーネントリストを表示してください。

# 現在のデザインルールを確認する
現在のデザインルールは何ですか?

# ボードプレビューを表示する
ボードのプレビューを表示してください。

# 全ての電気ネットをリストする
全ての電気ネットをリストしてください。


使用例

基本的なPCB設計ワークフロー
ドキュメントフォルダに「LEDBoard」という名前の新しいKiCADプロジェクトを作成してください。
ボードサイズを50mm x 50mmに設定して、矩形の外形線を追加してください。
各コーナーにマウンティングホールを配置してください。エッジから3mm、直径3mmです。
フロントシルクスクリーン上の位置x=25mm、y=45mmに「LED Controller v1.0」というテキストを追加してください。


コンポーネント配置
フットプリントLED_SMD:LED_0805_2012Metricを使用して、位置x=10mm、y=10mmにLEDを配置してください。
位置x=20mm、y=20mmから始まる4つの抵抗器 (R1-R4) のグリッドを5mm間隔で作成してください。
全ての抵抗器を水平に整列して、均等に配置してください。


ルーティング
「LED1」という名前のネットを作成して、R1のパッド2からLED1のアノードまで0.3mmのトレースをルーティングしてください。
ボード全体を覆う底面レイヤーのGND用の銅箔ポアを追加してください。
USB_PとUSB_Nのための差動ペアを0.2mm幅と0.15mmギャップで作成してください。


デザイン検証
0.15mmのクリアランスと0.2mmの最小トラック幅のデザインルールを設定してください。
デザインルールチェックを実行して、違反がないか確認してください。
fabricationフォルダにガーバーファイルをエクスポートしてください。


IPC API統合 (実験的)

KiCAD 9.0で導入されたIPC APIを使用することにより、リアルタイムUI同期が可能になる。

IPC APIの有効化

KiCADで IPC APIを有効化する。

[設定]メニューバー -　[設定...]メニュー - [プラグイン] - [KiCad APIを有効にする]チェックボックスにチェックを入力する。

IPC対応コマンド

以下に示すコマンドがIPC APIに対応している。

  • route_trace
    トレースのルーティング
  • add_via
    ビアの配置
  • place_component
    コンポーネントの配置
  • move_component
    コンポーネントの移動
  • delete_component
    コンポーネントの削除
  • add_copper_pour
    銅箔ポアの追加
  • refill_zones
    ゾーンの再塗りつぶし
  • add_board_outline
    ボード外形の追加
  • add_mounting_hole
    マウンティングホールの追加


ハイブリッドバックエンド

KiCAD-MCP-Serverは、IPC APIとSWIG APIのハイブリッドバックエンドを実装している。

  • IPC APIが利用可能な場合
    リアルタイムUI同期を使用
  • IPC APIが利用できない場合
    SWIG APIにフォールバック


この実装により、IPC APIのメリットを活用しながら、後方互換性を維持することができる。

IPC機能は実験的であり、現在テスト中である。
一部のコマンドは、全てのシナリオで期待通りに動作しない場合がある。

プロジェクト構造

KiCAD-MCP-Serverのプロジェクト構造を以下に示す。

KiCAD-MCP-Server/
├── src/                            # TypeScriptソースコード
│   ├── index.ts                    # メインエントリーポイント
│   ├── mcp-server.ts               # MCPサーバ実装
│   └── python-interface.ts         # Pythonサブプロセス管理
├── python/                         # Pythonインターフェース
│   ├── kicad_interface.py          # メインエントリーポイント
│   ├── kicad_api/                  # バックエンド実装
│   │   ├── base.py                 # 抽象基底クラス
│   │   ├── ipc_backend.py          # IPC APIバックエンド
│   │   ├── swig_backend.py         # SWIG APIバックエンド
│   │   └── factory.py              # バックエンドファクトリ
│   ├── schemas/                    # JSON Schema定義
│   │   └── tool_schemas.py         # ツールスキーマ
│   ├── resources/                  # リソースハンドラ
│   │   └── resource_definitions.py # リソース定義
│   └── commands/                   # コマンド実装
│       ├── project.py              # プロジェクト操作
│       ├── board.py                # ボード操作
│       ├── component.py            # コンポーネント配置
│       ├── routing.py              # トレースルーティング
│       ├── design_rules.py         # DRC操作
│       ├── export.py               # ファイル生成
│       ├── schematic.py            # 回路図設計
│       └── library.py              # フットプリントライブラリ
├── config/                         # 設定ファイル
├── docs/                           # ドキュメント
├── tests/                          # テスト
├── scripts/                        # ユーティリティスクリプト
├── package.json                    # Node.js依存関係
├── requirements.txt                # Python依存関係
├── tsconfig.json                   # TypeScript設定
└── README.md                       # プロジェクトドキュメント


トラブルシューティング

サーバがクライアントに表示されない

症状は、MCPサーバがClaude DesktopまたはClineに表示されないことである。

解決方法を以下に示す。

  • ビルドが完了していることを確認する。 
    ls dist/index.js
  • 設定ファイルのパスが絶対パスであることを確認する。
  • MCPクライアントを再起動する。
  • クライアントのログでエラーメッセージを確認する。


Pythonモジュールのインポートエラー

症状は、ModuleNotFoundError: No module named 'pcbnew' というエラーが発生することである。

解決方法を以下に示す。

  • KiCADのインストールを確認する。 
    python3 -c "import pcbnew"
  • 設定ファイルの環境変数 PYTHONPATH が、KiCADのインストールと一致しているか確認する。
  • KiCADがPythonサポート付きでインストールされていることを確認する。


ツール実行の失敗

症状は、ツールが不明確なエラーで失敗することである。

解決方法を以下に示す。

  • サーバログを確認する。
    ~/.kicad-mcp/logs/kicad_interface.log
  • ボード操作を実行する前にプロジェクトが読み込まれていることを確認する。
  • ファイルパスが相対パスではなく絶対パスであることを確認する。
  • ツールパラメータの型がスキーマ要件と一致しているか確認する。


Windows固有の問題

症状は、サーバがWindowsで起動しないことである。

解決方法を以下に示す。

  • 自動診断を実行する。 
    .\setup-windows.ps1
  • Pythonパスが二重バックスラッシュを使用しているか確認する。
    C:\\Program Files\\KiCad\\10.0
  • WindowsイベントビューアでNode.jsのエラーを確認する。
  • Windows Troubleshooting Guide (docs/WINDOWS_TROUBLESHOOTING.md) を参照する。


ヘルプの取得

問題が解決しない場合は、以下の方法でサポートを受けることができる。

  • GitHub Issues (https://github.com/mixelpixx/KiCAD-MCP-Server/issues) を確認する。
  • サーバログを確認する。(~/.kicad-mcp/logs/kicad_interface.log)
  • 以下の情報を含めて新しいissueを開く。
    オペレーティングシステムとバージョン、KiCADバージョン、Node.jsバージョン、完全なエラーメッセージとスタックトレース、関連するログの抜粋



参考情報



サーバ3 : Seeed-Studio/kicad-mcp-server

概要

Seeed-Studio/kicad-mcp-serverは、KiCad設計データの分析、検証、コード生成に重点を置くPython実装である。

ライセンスはMIT、最新コミットは2026年5月22日である。

KiCad 8.0以降に対応するが、KiCad 9.0または10.0を推奨する。

機能カテゴリ

Seeed-Studioのツールカテゴリ
カテゴリ ツール数 主な用途
Schematic Analysis 6 回路図の構造と接続の分析
PCB Analysis 6 基板、レイヤー、部品の分析
Netlist Analysis 4 ネットリストと接続関係の分析
Validation 3 設計の検証と問題の検出
Editing 6 分析結果に基づく編集とコード生成


インストール

KiCadに同梱されたPythonを使用する方法が推奨される。

KiCadバンドルPythonでは完全な pcbnew 分析を利用できる。

プロジェクトを取得し、編集可能モードでインストールする。

git clone https://github.com/Seeed-Studio/kicad-mcp-server.git
cd kicad-mcp-server

"C:\\Program Files\\KiCad\\10.0\\bin\\python.exe" -m pip install -e .


システムPythonでの導入も可能だが、この場合はテキストパースにフォールバックすることがある。

python -m pip install -e .


クライアント設定

KiCadバンドルPythonを使用するClaude Codeの設定例を示す。

 {
    "mcpServers": {
       "kicad": {
          "command": "C:\\Program Files\\KiCad\\10.0\\bin\\python.exe",
          "args": ["-m", "kicad_mcp_server"]
       }
    }
 }


システムPythonを使用する設定は、以下の通りである。

 {
    "mcpServers": {
       "kicad": {
          "command": "python",
          "args": ["-m", "kicad_mcp_server"]
       }
    }
 }


Claude Code CLIでは、次のコマンドでユーザスコープに追加できる。

claude mcp add kicad -s user -- "C:\Program Files\KiCad\10.0\bin\python.exe" -m kicad_mcp_server


OpenCode

OpenCodeでは、プロジェクトルートの opencode.json または opencode.jsonc に設定を記述する。

Seeed-Studio/kicad-mcp-serverをKiCadバンドルPythonで起動する設定例を以下に示す。

 {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
       "kicad": {
          "type": "local",
          "command": [
             "C:/Program Files/KiCad/10.0/bin/python.exe",
             "-m",
             "kicad_mcp_server"
          ],
          "enabled": true
       }
    }
 }


Linuxでは、KiCadバンドルPythonのパスを環境に合わせて変更する。
設定後、opencode mcp list コマンドを実行して、接続を確認する。

詳しい仕様は、OpenCode公式MCPサーバ設定を参照すること。

動作確認

  • KiCadのバージョンを確認する。 
    kicad-cli version
  • MCPクライアントを再起動する。
  • PCBの外形、部品、ネットを読み取るツールを順に実行する。
  • KiCadバンドルPythonで import pcbnew が成功することを確認する。



サーバ4 : oaslananka/kicad-mcp-pro

概要

oaslananka/kicad-mcp-proは、Schematic、PCB、ERC、DRC、DFM、BOM、製造レビューを1つのサーバで扱う統合型実装である。
KiCad 9.xと10.xに対応し、KiCadプログラム互換率は76.3[%]とされる。

ライセンスはMIT、最新リリースはv3.25.0である。

Python 3.13以降が必要である。

インストール方法

最も簡単な方法は、PyPIパッケージを uvx コマンドで実行する方法である。

uvx kicad-mcp-pro


npmラッパーを使う場合は次の通りである。

npx kicad-mcp-pro


GUIを使用する場合は、GitHub ReleasesからTauriデスクトップアプリのインストーラを取得する。
TauriアプリはPythonダッシュボードサーバを自動起動し、http://127.0.0.1:3334/ui でGUIを公開する。

STDIO設定

MCPクライアントの通常のローカル設定では、uvx をコマンドに指定する。

 {
    "mcpServers": {
       "kicad-pro": {
          "command": "uvx",
          "args": ["kicad-mcp-pro"]
       }
    }
 }


OpenCode

uvx を使用してkicad-mcp-proを起動する場合は、mcp フィールドにローカルサーバを定義する。

 {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
       "kicad-pro": {
          "type": "local",
          "command": [
             "uvx",
             "kicad-mcp-pro"
          ],
          "enabled": true
       }
    }
 }


特定のプロファイルを使用する場合は、command 配列の末尾にプロファイル名を追加する。
設定後、opencode mcp list コマンド と opencode mcp debug kicad-pro コマンドを実行して、接続を確認する。

詳しい仕様は、OpenCode公式MCPサーバ設定を参照すること。

Streamable HTTP

Streamable HTTPでは /mcp エンドポイントを使用する。
既定ポートは3334である。

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


HTTP時のMCPプロトコルバージョンは 2025-11-25 である。
既定では、ステートレスHTTPを使う。

セッションIDが必要な環境では、次の環境変数を設定する。

KICAD_MCP_STATEFUL_HTTP=1


LANやインターネットへ公開する場合は、127.0.0.1からバインド先を変更する前に、認証、ファイアウォール、TLS、プロジェクトパスの制限を設定する。

プロファイル

プロファイルを使うと、クライアントに公開するツールセットを制限できる。

  • full
    総合機能を公開する。
  • pcb_only
    PCB関連機能を公開する。
  • analysis
    解析とレビューを中心にする。
  • minimal
    必要最小限のツールだけを公開する。


解析機能の範囲

  • DFMと製造レビュー
  • SI、PI、EMC、熱解析の一次近似
    一次近似の精度目安は5から10%であり、正式な検証の代替ではない。
  • JLCPCB部品調達
  • Nexar、DigiKey、Mouser
    各APIを設定した場合に利用できる。


トラブルシューティング

3334ポートが使用中

Tauriアプリまたは別のプロセスが3334ポートを使用していると起動に失敗する。

  • 使用中のプロセスを確認する。
  • 別のポートを指定する。
  • MCPクライアントの接続先を同じポートへ変更する。


HTTP接続を許可できない

/mcp コマンドのエンドポイント、ホスト、ポート、MCP-Protocol-Versionを確認する。

ステートフル接続が必要な場合は、環境変数 KICAD_MCP_STATEFUL_HTTP=1 を設定する。


サーバ5 : belaszalontai/kipilot-mcp

概要

kipilot-mcpはKiCad 10.xだけを対象にしたPCB-firstのMCPサーバである。

Python 3.11以降を必要とし、KiCad 9以前には対応しない。

KiCad 10の公式kicad-python IPCバインディングのみを使用するため、SWIGとの自動フォールバックを前提にしない。

設計思想は読み取り主体であり、変更機能は KIPILOT_ENABLE_MUTATIONS=0 が初期値である。

インストール

ソースコードからインストールする場合は、リポジトリのルートで次を実行する。

git clone https://github.com/belaszalontai/kipilot-mcp.git
cd kipilot-mcp

pip install .


Windowsでは、ランタイムを含むZIPを使用できる。

kipilot-mcp-<version>-windows-x64.zip


ツールの範囲

接続確認
  • ping_kicad
    KiCadとのIPC接続を確認する。
  • get_kicad_version
    接続先のKiCadバージョンを取得する。


ボードとドキュメントの検査
  • ボード外形
  • スタックアップ
  • フットプリント
  • ネット
  • パッド
  • トラック
  • ビア
  • ゾーン


フィルタ検索
  • フットプリント検索
  • ネット検索
  • ネットクラス検索
  • 接続アイテム検索


ガード付き変更
  • レイヤーの変更
  • フットプリントの移動、回転、反転
  • トラックとビアの作成
  • ゾーンの再充填
  • 保存
  • リバート


利用手順

  1. KiCad 10のPCBエディタを起動する。
  2. MCPクライアントから ping_kicad を呼び出す。
  3. get_kicad_version で10.xを確認する。
  4. 検査ツールで現状を読み取る。
  5. 変更を行う場合だけ、環境変数 KIPILOT_ENABLE_MUTATIONS=1 を明示する。
  6. 変更後に検査を再実行し、保存前に差分を確認する。


トラブルシューティング

KiCad GUIへ接続できない

kipilot-mcpはIPC必須であり、KiCad GUIが起動していないと接続できない。
KiCad 10のPCBエディタで対象ボードを開いて、IPCプラグインの状態を確認する。

変更ツールが利用できない

変更は、既定で無効である。

意図した操作だけを行う場合に限り、環境変数 KIPILOT_ENABLE_MUTATIONS=1 を設定する。


サーバ6 : mixelpixx/Konnect

概要

mixelpixx/KonnectのKonnectは、KiCad専用として公開されているRust製MCPサーバである。
公式KiCad IPC APIを使用し、MCPのstdio通信でOpenCode等のクライアントへKiCad操作を提供する。

OpenCode連携ではスタンドアロン実行ファイルを使用する構成が扱いやすい。

ライセンスはAGPL-3.0である。

公式リポジトリと対応範囲

公式リポジトリは、mixelpixx/Konnectである。

Konnectは、回路図をS式形式のファイルとして編集して、PCBをKiCad 10のIPC API経由でリアルタイムに操作する構成を採用している。

PCB操作ではKiCad GUIが起動して、対象基板が開かれている必要がある。

Konnectの主な範囲は、以下の通りである。

  • 回路図の部品配置と配線
  • PCBのフットプリント配置、移動、回転、配線
  • ERC、DRC、接続性検証、設計レビュー監査
  • ガーバー、ドリル、BOM、ピックアンドプレース、3Dモデル、PDFのエクスポート
  • JLCPCB部品検索、Freerouting、リファレンス回路
  • 回路図ビューアと変更に追従する表示


Konnectの処理経路
対象 方式 KiCadの状態
回路図編集 .kicad_sch のS式編集と書き込み KiCadを起動せずに扱える範囲がある
PCB編集 KiCad 10 IPC API (NNG + protobuf) KiCad GUIと対象PCBが必要
DRC、ERC、エクスポート kicad-cliのサブプロセス kicad-cliのパスが必要
MCP接続 JSON-RPC over stdio OpenCodeのローカルMCPとして起動


配布物の選択

Linux向け配布物は、用途によって選択する。
両方を導入する必要はなく、OpenCode連携ではスタンドアロン版を使用する。

  • Konnect PCM
    KiCad Plugin and Content Manager用のプラグインパッケージである。
    metadata.json、plugin.json、Pythonランチャー、設定ダイアログ、Konnectバイナリを含む。
    KiCad内からインストールする場合に使用する。
  • Konnect スタンドアロン
    スタンドアロンのKonnectバイナリを含むアーカイブである。
    OpenCodeのstdio MCPサーバとして直接起動する場合は、こちらを推奨する。


Konnect PCMは、KiCad内のPlugin and Content Managerから導入する方式であり、Konnect スタンドアロンはKiCad外のMCPクライアントから実行ファイルを指定する方式である。

Linuxへの導入

Konnect スタンドアロンの配置

KonnectのReleasesから konnect-<バージョン>-<プラットフォーム>.tar.gz をダウンロードする。
ダウンロードしたファイルを解凍して、任意のディレクトリに配置する。

tar xf konnect-<バージョン>-<プラットフォーム>.tar.gz

mkdir -p ~/.local/bin
mv konnect ~/.local/bin/konnect
chmod u+x ~/.local/bin/konnect

~/.local/bin/konnect --version


環境変数 PATH に含まれていない場合でも、OpenCodeの設定では上記の絶対パスを指定することが可能である。

このバイナリはGNU libcに動的リンクされるため、Alpine Linux等のmusl環境ではそのまま動作しない場合がある。
そのため、musl環境では、互換性を確認するか適切なGNU libc環境で実行する。

OpenCodeの設定

OpenCodeでは、プロジェクトルートの opencode.json または opencode.jsonc のトップレベルにある mcp フィールドへ追加する。
全体設定を使用する場合は、Linuxでは ~/.config/opencode/opencode.json を使用する。

OpenCodeの形式では、mcp 配下の type、command、enabled を使用する。

既存のMCPサーバの設定がある場合は、既存サーバのブロックを削除せず、konnect ブロックだけを追加する。

以下の例では、kicad-proを登録するが、ツールの選択間違いを避けるため無効化している。

 // opencode.json / opencode.jsoncファイル
 
 {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
       "konnect": {
          "type": "local",
          "command": [
             "/home/<ユーザ名>/.local/bin/konnect"
          ],
          "enabled": true
       },
       "kicad-pro": {
          "type": "local",
          "command": [
             "uvx",
             "kicad-mcp-pro",
             "--transport",
             "stdio"
          ],
          "enabled": false
       }
    }
 }


/home/<ユーザ名>/.local/bin/konnectは、実際のログインユーザ名に置き換える。
設定を保存した後、OpenCodeを再起動して、以下に示すコマンドで接続を確認する。

opencode mcp list
opencode mcp debug konnect


Konnectの設定ファイル

Linuxでは、Konnectの設定ファイルとして ~/.config/konnect/config.toml ファイルを使用する。

OpenCodeのローカルstdio連携では、基本設定を次のようにする。

 # ~/.config/konnect/config.tomlファイル
 
 transport = "stdio"


また、IPCアドレスやkicad-cliのパスを環境に合わせて指定することもできる。
実際のソケットパスと実行ファイルの場所は、環境に合わせて変更すること。

 # ~/.config/konnect/config.tomlファイル
 
 transport = "stdio"
 kicad_cli = "/usr/bin/kicad-cli"
 kicad_binary = "/usr/bin/kicad"
 ipc_address = "ipc:///tmp/kicad/api.sock"


LinuxディストリビューションやKiCadの導入方法によってパスは異なるため、未確認のパスをそのまま固定値として扱わないこと。

KiCad IPC APIの有効化

KonnectのPCB操作は、KiCad 10の公式IPC APIをNNGとprotobufで利用する。

PCBを操作する前に、KiCad GUIとIPC APIを準備する。

  1. KiCad 10を起動する。
  2. [設定]メニューバー - [設定...]を開いて、[プラグイン]を選択する。
  3. [KiCad APIを有効にする]チェックボックスにチェックを入力する。
  4. PCB編集では、対象のPCBファイルをPCBエディターで開く。
  5. OpenCodeからKonnectの接続確認と読み取り操作を行う。
  6. 変更後はKiCad GUIの表示、Undo履歴、DRC結果を確認して保存する。


回路図の直接編集はKonnectのS式エンジンによるファイル操作であり、PCBのGUI操作は起動中のKiCad IPC APIを経由する。

一方、DRC、ERC、ガーバー等のチェックとエクスポートは、kicad-cliサブプロセスの役割とされている。
したがって、回路図編集、PCBのGUI IPC操作、kicad-cliによるチェックと出力を同じ接続経路として扱わない。

kicad-mcp-proとの併用

Konnect と oaslananka/kicad-mcp-pro をOpenCodeへ両方登録することは可能である。
ただし、類似したPCB、DRC、ERC、エクスポート系のツールが同時に有効になると、AIが意図しないサーバを選ぶ可能性がある。

運用方法は、次のいずれかに固定する。

  • 編集担当をKonnectに固定して、kicad-mcp-proはレビューと解析専用にする。
  • OpenCodeの設定において、作業時に使用するサーバだけを enabled: true にする。
  • 両方を登録したまま、AIへの運用指示で担当範囲を明示する。


同じ .kicad_sch または .kicad_pcb を、Konnectとkicad-mcp-proから同時に編集してはならない。
編集前にプロジェクトを複製して、どちらか一方のMCPサーバによる操作を完了してから、もう一方をレビューに使用する。

OpenCodeでの運用指示例を以下に示す。

 - PCBと回路図の編集担当はKonnectに固定する。
 - kicad-mcp-proは読み取り、レビュー、解析だけに使用する。
 - 同じ .kicad_sch または .kicad_pcb を両MCPサーバから同時に編集しない。
 - 変更前に複製とバックアップを作成して、変更対象と保存可否を確認する。
 - Konnectで編集した後、KiCad GUIで確認して、kicad-mcp-proでレビューする。
 - DRC、ERC、エクスポートは使用したMCPサーバとkicad-cliの結果を照合する。


Konnectのトラブルシューティング

Exec format error

Exec format error エラーが表示される場合は、実行環境とバイナリのアーキテクチャが一致していない可能性がある。

  • uname -m コマンドで実行環境を確認する。
  • x86_64 と表示される場合は、konnect-<バージョン>-x86_64-unknown-linux-gnu.tar.gz を使用する。
  • ARM環境では、対応する別の配布物 または ソースコードからビルドする。


Permission denied

Permission denied エラーが表示される場合は、実行権限を付与する。

chmod u+x ~/.local/bin/konnect


IPC接続失敗

PCBツールがIPC接続に失敗する場合は、次の順に確認する。

  • KiCad 10のGUIが起動していることを確認する。
  • [設定]メニューバー - [設定...] - [プラグイン]を選択して、[KiCad APIを有効にする]チェックボックスにチェックを入力する。
  • 対象PCBをPCBエディターで開く。
  • ~/.config/konnect/config.toml ファイルの ipc_addressと、KiCad側のソケット設定を確認する。
  • opencode.json ファイルの command がスタンドアロン版のフルパスを指していることを確認する。


kicad-cliの検出失敗

kicad-cli not found エラー等が表示される場合は、kicad-cliが環境変数 PATH にあるか、設定ファイルのkicad_cliのパスが正しいかを確認する。

which kicad-cli
kicad-cli version


KiCadのインストール先が標準外の場合は、~/.config/konnect/config.toml ファイルにフルパスを指定する。


その他の実装

主要な6つのMCPサーバ以外にも、用途を絞ったものが存在する。

Glama.aiに登録された実装

サーバ ツール数 特徴
bleugreen/kicad-mcp - マルチボード接続トレース、データシート検索
lmaag182/kicad_mcp_server_ipc 77 IPC APIのみ、KiCad 9+
daedalus/mcp-kicad 約17 PyPIのmcp-kicad v0.1.1
ProductOfAmerica/mcp-server-kicad 102 5サーバスイート
SaeronLab/eda-mcp 39 KiCad 9.x、EDA汎用
fsbondtec/kicad-mcp - lamaalrajihのフォーク
skeptomai/kicad_mcp - SQLite FTS5による20,000以上の部品検索


Huaqiu Electronicsの組み込み実装

Huaqiu-Electronics/kicad-mcpはKiCadフォークに組み込まれたMCPサーバである。

72ツールを含み、フォーク元はKiCad 9.0リリースブランチを追跡する。

公式KiCadへのマージ状況は不明であるため、導入前にフォークとの差分と保守状態を確認する。

その他の専門実装

サーバ 主な用途 状態
circuit-synth/mcp-kicad-sch-api 回路図操作特化 専門実装
Netlist-Studio/kicad-mcp KiCad 9 IPC API制御 IPC中心
blwfish/kicad-mcp 71ツール、FastMCP、kicad-sch-api 複合実装
Greg3001/kicad-claude-mcp 105ツール、SPICE、SI、RF、パネル化 拡張型
Finerestaurant/kicad-mcp-python 公式IPC API 2025年7月以降開発停止


用途が限定されるサーバは、主要サーバの代替ではなく、対象機能の補助として評価する。
特に、KiCad 10のフォーマットとIPC APIを使用する場合は、最終コミット日だけでなく、実際のサンプルプロジェクトで確認する。


MCPプロトコルと接続方式

MCPはLLMホスト、クライアント、サーバの間でコンテキストとツールを標準化する。
メッセージ形式はJSON-RPC 2.0で、サーバとクライアントは能力をネゴシエーションする。

プロトコル階層

  • JSON-RPC 2.0
    リクエスト、レスポンス、エラーのメッセージ形式を定める。
  • MCP Base Protocol
    初期化、能力交渉、通知、キャンセル、ログを定める。
  • Server Features
    Resources、Prompts、Toolsを定める。


STDIO

STDIOは全主要サーバが対応するローカル向けの接続方式である。
プロセスの標準入力と標準出力をJSON-RPC通信に使うため、標準出力へデバッグログを出力してはならない。

Streamable HTTP

oaslananka/kicad-mcp-proはStreamable HTTPに対応する。
リモートや複数クライアントから利用できるが、HTTP公開時には認証、許可オリジン、TLS、プロジェクトディレクトリ制限を検討する。


共通の設定と運用

Claude Desktopの設定

設定ファイルの場所はLinuxでは ~/.config/Claude/claude_desktop_config.json、Windowsでは %APPDATA%\Claude\claude_desktop_config.json である。
サーバごとに実行ファイルと引数を絶対パスで指定する。

 {
    "mcpServers": {
       "kicad": {
          "command": "/home/<ユーザ名>/.local/bin/uvx",
          "args": ["kicad-mcp-pro"]
       }
    }
 }


OpenCodeの設定

OpenCodeでは、opencode.json または opencode.jsonc の mcp フィールドに、使用するMCPサーバを定義する。

kicad-mcp-proを使用する例を以下に示す。

 {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
       "kicad-pro": {
          "type": "local",
          "command": [
             "uvx",
             "kicad-mcp-pro"
          ],
          "enabled": true
       }
    }
 }


OpenCodeのプロジェクト設定はプロジェクトルートに配置して、全プロジェクト共通の設定はLinuxでは ~/.config/opencode/opencode.json に配置する。

command は実行ファイルと引数を1つの配列にまとめる。
設定後、opencode mcp list コマンドを実行して、サーバ一覧を確認する。

詳しい仕様は、OpenCode公式MCPサーバ設定を参照すること。

パス制限

AIから参照できるディレクトリは、KiCadプロジェクト専用ディレクトリに限定する。
既存ページで使用していた検証例を次に示す。

 from pathlib import Path
 
 ALLOWED_DIRECTORIES = [
    "/home/<ユーザ名>/kicad-projects",
    "/home/<ユーザ名>/shared-projects",
 ]
 
 def is_path_allowed(file_path: str) -> bool:
    try:
       resolved_path = Path(file_path).resolve()
       return any(
          resolved_path.is_relative_to(Path(item).resolve())
          for item in ALLOWED_DIRECTORIES
       )
    except Exception:
       return False


バックアップ

変更を許可するサーバでは、ツール呼び出し前にスナップショットを作成する。

既存のバックアップ例を示す。

 #!/usr/bin/env sh
 
 BACKUP_DIR="/var/backups/kicad-projects"
 DATE=$(date +%Y%m%d_%H%M%S)
 PROJECT_DIR="/home/username/kicad-projects"
 
 mkdir -p "$BACKUP_DIR"
 
 tar -czf "$BACKUP_DIR/kicad-projects_$DATE.tar.gz" \
    -C "$(dirname "$PROJECT_DIR")" "$(basename "$PROJECT_DIR")"
 
 find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete
 
 echo "バックアップ完了: kicad-projects_$DATE.tar.gz"


Systemdでの運用

STDIOサーバをSystemdで常時起動する場合は、専用ユーザと限定された作業ディレクトリを使用する。

 [Unit]
 Description=KiCAD MCP Server
 After=network.target
 
 [Service]
 Type=simple
 User=<実行する任意のユーザ名>
 WorkingDirectory=/home/<ユーザ名>/kicad-mcp-server
 ExecStart=/home/<ユーザ名>/kicad-mcp-server/venv/bin/python server.py
 Restart=on-failure
 RestartSec=10
 StandardOutput=journal
 StandardError=journal
 
 [Install]
 WantedBy=multi-user.target



systemctl --user daemon-reload
systemctl --user enable kicad-mcp-server
systemctl --user start kicad-mcp-server
journalctl --user -u kicad-mcp-server -f



トラブルシューティング

KiCad 10のシャーディングエラー

kicad_symdir のシャーディングを認識できない場合は、mixelpixx/KiCAD-MCP-Serverをv2.3.1以降へ更新する。

古いMCPサーバを使用する場合は、KiCad 9形式の複製プロジェクトで処理し、原本を上書きしない。

フォーマットバージョン20260101の認識エラー

KiCad 10.0.0以降を使用して、サーバ側のKiCad 10対応状況を確認する。

MCPサーバのログに古いフォーマットエラーが出る場合は、更新後にプロセスとMCPクライアントを再起動する。

Python 3.9のwrite_text非互換

mixelpixxの古いバージョンでPython 3.9の write_text 引数非互換が発生する場合は、v2.3.1へ更新する。

IPCで回路図を操作できない

KiCad 10では回路図エディタのIPC APIは未対応である。

SWIG、回路図専用API、またはサーバが提供するテキスト解析を使い分ける。

PCB操作と回路図操作を同じIPC接続だけで実現しようとしない。

lamaalrajihがKiCad 10で動かない

lamaalrajih/kicad-mcpはKiCad 9.0のみ対応で、2025-10以降は開発停止状態である。

KiCad 10では動作しない可能性が高いため、KiCad 9専用の隔離環境で使用するか、対応サーバへ移行する。

kipilot-mcpが接続できない

KiCadを起動して、対象PCBを開いてから ping_kicad を実行する。

IPC必須であるため、ヘッドレス環境やKiCad未起動の環境では接続できない。

STDIOのサーバが表示されない

  • 実行ファイルの絶対パスを確認する。
  • 引数の順序と作業ディレクトリを確認する。
  • 標準出力へログを出力していないか確認する。
  • MCPクライアントを完全終了して再起動する。
  • サーバ単体でバージョン確認コマンドを実行する。


DRC、ERC、ガーバー出力が失敗する

IPC APIはプロットとエクスポートを提供しない。

エクスポートには kicad-cli を使用して、出力先の書き込み権限とディスク容量を確認する。

DRCまたはERCの結果は、使用サーバの解析機能とKiCad本体の結果を照合する。

大規模PCBで応答が遅い

  • 解析対象をプロファイルやパスで限定する。
  • 読み取りを複数回繰り返さず、結果をキャッシュする。
  • 変更操作を一つずつ承認する。
  • 長時間処理にタイムアウトを設定する。
  • 不要なボードオブジェクトを解放する。



外部リンク



実運用ワークフロー

導入前の確認

導入前に、KiCad本体、Python、Node.js、IPCの対応範囲を別々に確認する。

確認項目 確認方法 判断
KiCad本体 kicad-cli version 9.xまたは10.xを記録する。
PCB API バンドルPythonで import pcbnew 完全分析が必要なら成功を確認する。
IPC KiCad GUI起動後にping IPC専用サーバでは必須
MCPクライアント サーバ一覧を表示 STDIOまたはHTTPを確認する。
プロジェクト 複製を作成 原本を直接変更しない。


読み取りから変更へ進む

安全な順序は、接続確認、読み取り、解析、差分確認、変更、再検証、保存である。

  1. サーバを起動する。
  2. クライアントでサーバのツール一覧を取得する。
  3. KiCadのバージョンを確認する。
  4. プロジェクト、ボード、回路図のパスを確認する。
  5. 部品、ネット、レイヤー、ゾーンを読み取る。
  6. DRCまたは検証結果を取得する。
  7. 変更内容をAIの応答で確認する。
  8. 変更ツールを1つずつ承認する。
  9. KiCad本体で結果を目視確認する。
  10. 保存前にバックアップと差分を作成する。
  11. DRC、ERC、製造データの検証を再実行する。


AIへの依頼文の設計

依頼文には対象ファイル、操作対象、単位、許可する変更、検証条件を明記する。

# 良い依頼の例:
複製した ~/projects/led/led.kicad_pcb を読み取り、フットプリント数と未接続ネットだけを報告してください。
変更は行わないでください。



# 変更を含む依頼の例:
複製ボードのF.Cuだけを対象に、USB差動対の幅と間隔を確認してください。
問題がある場合は変更案を提示し、承認なしでは保存しないでください。


単位と座標

KiCadの寸法は通常mmで扱うが、APIの実装によっては内部単位を使う。

ツールの説明に単位がない場合は、変更前に取得した値とKiCad GUIの表示を照合する。

座標、レイヤー名、ネット名、リファレンスを省略せず指定する。

変更の承認

書き込みツールは、読み取りツールと分離して公開する。

読み取り主体のkipilot-mcpでは、変更を明示的に有効化した時だけ書き込みを許可する。

総合型サーバでは、クライアント側の自動承認リストを空にすることを基本とする。

ログとプライバシー

ログにはプロジェクトパス、ツール名、実行時間、結果の要約を記録する。

回路図、ネットリスト、部品表に含まれる機密情報を外部へ送信しない。

STDIOのJSON-RPC通信を壊さないため、通常ログは標準エラー出力かファイルへ出力する。

大規模PCBの処理

大規模な基板では、一度に全オブジェクトをAIへ返さない。
まず集計値を取得し、必要なリファレンス、ネット、レイヤーに絞って詳細を取得する。

  • 最初にボードの外形と層数を取得する。
  • 次にフットプリント数とネット数を取得する。
  • 次に問題のあるネットだけを検索する。
  • 最後に対象部品のパッドとトラックを取得する。


エクスポートの分離

ガーバー、PDF、SVG、3D、BOMの生成は、使用サーバが対応するか確認する。

IPCだけで完結しない場合は kicad-cli を外部コマンドとして使用する。

出力ディレクトリはプロジェクト外の一時ディレクトリにし、生成物をレビュー後に移動する。

失敗時の復旧

変更の途中でエラーが出た場合は、プロセスを再起動する前にログとプロジェクトの状態を保存する。

未保存のKiCad GUI状態とファイル上の状態が異なる可能性があるため、GUI上のUndoとバックアップを併用する。

  1. ツールの実行を停止する。
  2. KiCad GUIで変更履歴を確認する。
  3. 直前のバックアップとファイルのハッシュを比較する。
  4. 必要なら複製プロジェクトへ戻す。
  5. 問題を再現できる最小プロジェクトを作る。
  6. OS、KiCad、Python、Node.js、MCPサーバのバージョンを記録する。


サーバ更新の手順

更新前に、リポジトリのコミット、依存関係、クライアント設定を保存する。

  1. 現在のMCPサーバのバージョンを記録する。
  2. プロジェクトをバックアップする。
  3. 新しい版を別ディレクトリへ導入する。
  4. 小さなテストプロジェクトで接続する。
  5. 読み取りツールを検証する。
  6. 書き込みを含む機能を複製上で検証する。
  7. 問題がなければクライアント設定を切り替える。


互換性の記録

プロジェクトごとに、KiCadのバージョン、MCPサーバのバージョン、Pythonのバージョン、利用したトランスポートを記録する。
特に、kicad_symdir、フォーマットバージョン 20260101、IPC接続の有無を記録する。

記録項目 例
KiCad 10.0.0
サーバ mixelpixx/KiCAD-MCP-Server v2.3.1
Python 3.9以降またはサーバ要件に従う。
トランスポート STDIO
IPC KiCad GUIで有効
プロジェクト形式 20260101、kicad_symdir
バックアップ 実行前に作成



実装例の再利用

既存ページのFastMCP実装例は、lamaalrajih/kicad-mcpのような小規模サーバを拡張する場合の出発点として利用できる。

ただし、例はKiCad 9のSWIG APIを前提にしているため、KiCad 10でそのまま動作するとは限らない。

安全なボード読み込み

 import logging
 from pathlib import Path
 import pcbnew
 
 logger = logging.getLogger(__name__)
 
 def safe_load_board(kicad_pcb_path: str):
    try:
       path = Path(kicad_pcb_path).resolve()
       if not path.exists():
          logger.error("ファイルが存在しません: %s", path)
          return None
       if path.suffix != ".kicad_pcb":
          logger.error("PCBファイルではありません: %s", path)
          return None
       return pcbnew.LoadBoard(str(path))
    except Exception:
       logger.exception("PCB読み込みエラー")
       return None


結果を小さく返す

AIへ返す結果は、必要なフィールドだけに絞る。

 def board_summary(board: pcbnew.BOARD) -> dict:
    return {
       "layer_count": board.GetCopperLayerCount(),
       "track_count": board.GetTracks().GetCount(),
       "footprint_count": len(list(board.GetFootprints())),
    }


標準出力の保護

STDIOサーバでは、起動時の診断文字列を標準出力へ出力しない。

 import logging
 import sys
 logging.basicConfig(stream=sys.stderr, level=logging.INFO)


KiCad 10への移行

  • kicad_symdir の探索を追加する。
  • フォーマットバージョン 20260101 を認識する。
  • KiCad 10のバンドルPythonでAPIを検証する。
  • IPCとSWIGの機能差を文書化する。
  • 回路図操作をIPCだけに依存しない。
  • エクスポートを kicad-cli に委譲する。



運用上の注意

ライセンスと計画中の実装

主要サーバのライセンスはMITが多いが、個々のリポジトリのライセンス表示を導入時に確認する。

KonnectはKiCad 10専用、v0.2.0 BETAのRust製MCPサーバである。
READMEには185ツールと18ツールセットと記載されている一方、リポジトリの別箇所には171ツールの表記もあるため、数え方が異なる可能性がある。
実際の導入時は、使用するリリースのREADMEとライセンス条件を確認する。

詳細な導入手順、OpenCode設定、kicad-mcp-proとの併用方針は、サーバ6 : mixelpixx/Konnectにまとめる。

注意事項

KiCad 10では、MCPサーバの選択にファイル形式とIPC対応の確認が欠かせない。

総合操作にはmixelpixx、分析にはSeeed-Studio、HTTPにはoaslananka、読み取り主体のKiCad 10運用にはkipilot-mcpが適している。
lamaalrajihは、KiCad 9専用の既存資産として隔離して扱う。

導入後は、バックアップ、パス制限、承認制、KiCad本体での再検証を運用手順に組み込む。
更新時は、サーバのリリースノートとKiCadのフォーマット変更を照合する。

KiCad 10対応を明記していない実装では、複製プロジェクトを使用する。

HTTP接続はローカルバインドを基本として、公開する場合は保護機構を追加する。

回路図操作とPCB操作は、APIの対応範囲を分けて検証する。

エクスポートはIPCの制限を考慮して、必要に応じてkicad-cliへ委譲する。

これらの確認により、AIによる設計支援と再現可能なレビューを両立できる。

最終判断は設計者が行い、MCPサーバを検証工程の代替にしないことが重要である。


「https://mochiu.net/index.php?title=MCPサーバ_-_KiCAD&oldid=15174」から取得