KiCad Tools

mcp-server-kicad

AI アシスタントが、実際の KiCad プロジェクトを壊さずに編集できるようにします。

回路図の作成、PCB レイアウト、シンボルとフットプリントのライブラリ、ERC と DRC、製造用エクスポートをカバーする 109 個の MCP ツールです。スクリーンショットも、コピー＆ペーストも、S 式の手動編集も不要です。モデルがツールを呼び出すと、KiCad ファイルがディスク上で変更されます。

クイックスタート • 利用できる機能 • 設定 • ツールリファレンス • 要件 • コントリビューション

重要

メンテナンスモードです。 2026 年 10 月時点で、このプロジェクトではセキュリティ修正と KiCad 互換性の修正のみを行っています。新しいツールや機能を追加する予定はありません。既存のインストールは引き続き動作します。理由

メンテナンスモードの理由

このプラグインは、「KiCad ファイルは大きいため、AI アシスタントはテキストを編集するのではなく、ツールを使って変更すべきだ」という考えに基づいて作られました。この考えを、KiCad をインストールした状態でプラグインを使わない Claude Code と比較して検証しました。同じモデル（Claude Opus 5.5）、同じ設定、同じタスクを使い、各結果を KiCad 10 自体で判定しました（ネットリスト、基板、ERC、DRC）。

• 6 件の個別編集を、公開されている KiCad 10 の設計で実施しました（値の変更、実装しない設定、フットプリントの交換、パッドへのネット割り当て、フットプリントの回転、シートをまたいだネット名の変更）。各タスクを 3 回実行したところ、プラグインなしの Claude Code は 18 件すべてに正解しました。プラグインを使った場合は、18 件中 3 件が正解でした。
• 基板を 20 回編集する長時間のセッション。 どちらもすべての編集に正解しましたが、プラグインのセッションでは約 1.8 倍のコンテキストを使用しました。
• プラグインが失敗した理由を、すべてのトランスクリプトを確認して調べました。
  • 一部の編集（パッドのネット、実装しないフラグ、フットプリントの交換）に対応するツールがありませんでした。
  • 指示によって、KiCad ファイルを直接編集しないようモデルに伝えていたため、モデルは作業を中断して質問しました。
  • 基板同期ツールは基板上のほぼすべてのフットプリントを書き換えたため、モデルは自分の作業を元に戻しました。
• 今回のテストでは、前提は成り立ちませんでした。 プラグインなしの Claude Code は、2 MB の基板全体を読み込まず、部品を検索して必要な行だけを編集しました。

これらは 1 つの設計を使った小規模なテストであり、あらゆる基板やモデルに対する結論ではありません。ただし、ツールの追加をやめるには十分な結果でした。使用した設計にはライセンスがないため、テスト資料は公開していません。

代わりに使用するもの： KiCad をインストールしたうえで、Claude Code などのコーディングエージェントを使用してください。完了前に kicad-cli（ネットリストのエクスポート、ERC、DRC）で変更を確認するよう指示してください。

バグ報告や KiCad 互換性の修正は、引き続き歓迎します。

使用イメージ

"Add a 100 nF decoupling cap on U1's VCC pin, then check ERC."

  get_pin_positions            locate U1's VCC and GND pins
  auto_place_decoupling_cap    place C3 and wire both pins to their nets
  run_erc                      report what the change broke

"Now push the netlist to the board and route it."

  update_pcb_from_schematic    sync footprints and pad nets onto the PCB
  autoroute_pcb                route with Freerouting
  run_drc                      clearance, width, and unconnected checks

すべてのツールは実際のファイルを対象に動作し、書き込みによって変更されるのは指定したバイトだけです。正しく実行できない編集は、ファイルをそのまま保持して拒否されます。KiCad 自体が設計ファイルを書き込むのは 2 か所だけです。ライブラリのアップグレードと、ルーティング済みのコピーを作成する autoroute_pcb です。後者は新しい基板を作成し、元の基板には手を加えません。

クイックスタート

Claude Code

プラグインをインストールします。サーバーを設定し、デザインスキルも同梱します：

claude plugin marketplace add ProductOfAmerica/mcp-server-kicad
claude plugin install kicad

Claude Desktop

最新リリースからkicad-<version>.mcpbをダウンロードし、Settings、次にExtensionsからインストールします。Claude DesktopがPythonとパッケージ本体を取得します。KiCadをインストールしておく必要があり、autoroute_pcbを使うにはJava 25以降も必要です。

デスクトップアプリはプロジェクトのディレクトリから実行されないため、求められた回路図、基板、エクスポート先のパスを入力してください。KiCadが通常とは異なる場所にインストールされていない限り、kicad-cliフィールドは空欄にしてください。デザインスキルはClaude Code専用です。

その他すべて

pip install mcp-server-kicad

次に、MCP クライアントを統合サーバーに接続し、毎回の呼び出しで指定しなくてもツールがパスを参照できるように、回路図、基板、エクスポート先フォルダーをenvに絶対パスで指定します：

{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad"],
      "env": {
        "KICAD_SCH_PATH": "/path/to/project/project.kicad_sch",
        "KICAD_PCB_PATH": "/path/to/project/project.kicad_pcb",
        "KICAD_OUTPUT_DIR": "/path/to/project"
      }
    }
  }
}

このエントリーだけで、109個すべてのツールが登録されます。サーバーをプロジェクトのフォルダーで起動するクライアントの場合、envは省略できます。その場合、サーバーはそこにある単一の.kicad_proからパスを取得します（パスの解決方法を参照）。ツールを5つの小さなサーバーに分けたい場合は、設定を参照してください。

利用できる機能

5つのツールサーバー

統合サーバーとして実行することも、コンテキスト内で利用するツールを絞りたい場合に個別に実行することもできます。

6つのデザインスキル（Claude Codeプラグイン）

ツールだけでも、モデルはすべてのボタンをクリックできます。同梱のスキルは、どのボタンをどの順番で使い、何をもって「完了」とするかを教えます。

デザインスキルは、次に進む前に成果物を独立したレビュアーサブエージェント（agents/）に渡します。そのため、不適切なBOMや配置計画が回路図になる前に見つかります。

設定

サーバーの分割

ツールの一部だけを読み込みたい場合は、1つではなく5つのエントリーを使います：

{
  "mcpServers": {
    "kicad-schematic": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-schematic"]
    },
    "kicad-pcb": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-pcb"]
    },
    "kicad-symbol": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-symbol"]
    },
    "kicad-footprint": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-footprint"]
    },
    "kicad-project": {
      "command": "uvx",
      "args": ["--from", "mcp-server-kicad", "mcp-server-kicad-project"]
    }
  }
}

uvx --from mcp-server-kicad mcp-server-kicad-schematic

優先順位の高いものが適用されます。

1. ツールのパラメーター。 すべてのツールで明示的にパスを指定できます。
2. 環境変数。 自動検出された値より優先されます。
3. 自動検出。 作業ディレクトリを検索して .kicad_pro を見つけ、そこから回路図、基板、ライブラリのパスを特定します。

要件

• Python 3.11 以降

• KiCad 9.x または 10.x。KiCad を呼び出すツールに限ります。

  • kicad-cli：ERC、DRC、エクスポート、ジョブセット、get_version、ライブラリのアップグレード、update_pcb_from_schematic
  • pcbnew Python バインディング：fill_zones と autoroute_pcb（Java 25 以降も必要です。Freerouting のダウンロードを参照してください）
  • KiCad の標準ライブラリ：標準シンボルまたはフットプリントの配置

  それ以外のツールはすべてファイルを直接解析するため、KiCad は不要です。

CI は Linux（KiCad 9 および 10）、macOS と Windows（KiCad 10）、および Python 3.11～3.14 を対象としています。

Freerouting のダウンロード

autoroute_pcb は Freerouting を実行します。 FREEROUTING_JAR で jar が指定されていない場合、初回の実行時に Freerouting 2.5.0 の freerouting-2.5.0.jar（65 MB、Java 25 以降が必要）を https://github.com/freerouting/freerouting/releases/download/v2.5.0/freerouting-2.5.0.jar からダウンロードし、~/.local/share/mcp-server-kicad/freerouting-2.5.0.jar （Windows では %USERPROFILE%\.local\share\mcp-server-kicad\）にキャッシュします。SHA-256 は、このパッケージに固定されている値と照合され、ダウンロードの保存前とキャッシュ済みのコピーを使用するたびに検証されます。一致しないダウンロードは保存されません。一致しないキャッシュ済みのコピーは実行されず、再度ダウンロードされます。

Freerouting は --gui.enabled=false と --usage_and_diagnostic_data.disable_analytics=true を指定して実行されます。これらは、ヘッドレスでの実行と使用状況データを送信しないためにドキュメントで指定されている設定です。そのため、ウィンドウは開かず、分析機能もオフのままです。起動時に Freerouting は引き続き GitHub に最新リリースを問い合わせます。これを無効にする設定はありません。

ダウンロードをスキップするには、信頼できる Freerouting の jar の絶対パスを FREEROUTING_JAR に設定してください。その jar はハッシュ検証なしで、指定されたとおりに使用されます。相対パス、または存在しないファイルを指定するパスは無視され、ダウンロードが実行されます。以前のリリースでは、同じフォルダーに未検証の freerouting.jar がキャッシュされていましたが、現在は読み込まれないため、削除できます。

KiCad のインストール先を見つける

標準インストールでは設定は不要です。kicad-cli はまず PATH から、次に macOS では /Applications/KiCad/KiCad.app から、Windows では Program Files と AppData から新しいものを優先して検索されます。標準ライブラリと pcbnew の Python は、その場所を基準に検索されます。一般的でないインストールの場合は、次の変数を設定してください。

kicad-cli が見つからない場合、それを必要とするツールは一覧に表示されたままになり、KICAD_CLI_PATH を示すメッセージとともに失敗します。

KiCad 10 ファイル

サーバー独自の読み書き機能は、KiCad 9 と 10 の回路図、基板、シンボルライブラリ、フットプリントを同様に扱い、変更を依頼していないバイト列は一切変更しません（ docs/adr-cst-substrate.md を参照）。KiCad 自体に処理を任せる場合は、インストール済みの KiCad でファイルを読み込める必要があります。KiCad 9 では KiCad 10 の基板を読み込めません。

• fill_zones と autoroute_pcb は、KiCad 9 の pcbnew で KiCad 10 の基板を処理しようとすると、開始前に拒否します。KiCad 10 をインストールするか、KICAD_PYTHON を KiCad 10 のものに設定してください。KiCad 10 の pcbnew を使って KiCad 9 の基板に対して autoroute_pcb を実行することはできますが、ルーティング済みのコピーは KiCad 10 形式で出力されるという警告が表示されます。元の基板には一切触れません。
• upgrade_symbol_lib と upgrade_footprint_lib は、仕様として KiCad にファイルを書き換えさせます。各ファイルは変更があった場合にのみアトミックに置き換えられるため、アップグレードが中断しても破損したファイルは残りません。バックアップは <name>.bak に保存され、実行のたびに上書きされます。

Windows：コントロールされたフォルダーアクセス

Defender のコントロールされたフォルダーアクセスは、KiCad がデータを保存する Documents の下への、認識されていないアプリによる書き込みをブロックします。そのため、kicad-cli はすべての呼び出しで起動時にクラッシュし、--version も例外ではありません（終了コード 3221225477）。エラーはファイルが見つからないように見えます：error 2: The system cannot find the file specified。

サーバーは回避策として、KICAD_DOCUMENTS_HOME を保護されていないローカルフォルダーに設定して一度再試行し、その設定をセッション中維持します。フォルダーを自分で選ぶ場合は、KICAD_DOCUMENTS_HOME を設定してください（これにより再試行は無効になります）。

プロジェクトファイルの問題は解決できません。 プロジェクトが Documents の下にある場合、書き込みツールも同様に失敗します。プロジェクトを移動するか、Windows セキュリティ > ウイルスと脅威の防止 > ランサムウェアの防止 > コントロールされたフォルダーアクセスでアプリを許可する、からツールを許可してください。

ツールリファレンス

デバッグ

MCP Inspector を使って、サーバーを手動で操作します。

npx -y @modelcontextprotocol/inspector uvx --from mcp-server-kicad mcp-server-kicad

コントリビュート

Issue とプルリクエストを歓迎します。開発環境のセットアップについては CONTRIBUTING.md を、バイトを保持する書き込み経路の設計判断については docs/adr-cst-substrate.md をご覧ください。

• バグを報告する
• オープン中の Issue を見る
• セキュリティポリシー
• 行動規範

ライセンス

GPL-3.0-or-later。0.20.1 以前のリリースは MIT ライセンスでした。詳しくは NOTICE をご覧ください。