MCPサーバ - KiCAD

概要

KiCAD MCPサーバは、電子回路設計ソフトウェアであるKiCADをAIアシスタントから操作可能にするためのModel Context Protocol (MCP) サーバである。
このMCPを使用することにより、Claude等のLLMがKiCADプロジェクトの管理、回路図の操作、PCBレイアウトの編集等を実行することができる。

現在、2つの異なるKiCAD MCPサーバの実装が存在する。

• lamaalrajih/kicad-mcp

  Python実装のサーバで、FastMCPを使用した軽量な実装である。

  基本的なPCB操作、DRC実行、Gerberファイル出力等の機能を提供する。

• mixelpixx/KiCAD-MCP-Server

  TypeScriptとPythonのハイブリッド実装で、より高度な機能を提供する。

  52のツール、8のリソース、回路図操作、IPC統合等の包括的な機能を備えている。

KiCAD MCPサーバは、以下に示すような機能を提供する。

• KiCADプロジェクトファイルの読み込みと解析
• 回路図の情報取得
• PCB基板レイアウトの情報取得
• コンポーネントライブラリの管理
• ネットリストの生成と検証
• Design Rule Check (DRC) の実行
• Electrical Rule Check (ERC) の実行
• Gerberファイル等の製造データの出力

両MCPとも、Standard I/O (STDIO) トランスポートを使用してローカル環境で動作する。
これにより、Claude Desktop、Claude Code、Cursor等のMCPクライアントと統合することができる。

サーバの比較

下表に、2つのKiCAD MCPサーバの違いを示す。

KiCAD MCPサーバの比較

特徴	lamaalrajih/kicad-mcp	mixelpixx/KiCAD-MCP-Server
実装言語	Python (FastMCP)	TypeScript + Python
ツール数	基本的なツールセット	52ツール
リソース	なし	8リソース
回路図操作	なし	あり (kicad-skip使用)
IPC統合	なし	あり (実験的)
JLCPCB統合	なし	開発中
プラットフォーム	Linux中心	Linux、Windows、macOS
プロトコル準拠	MCP基本実装	MCP 2025-06-18完全準拠
セットアップの複雑さ	シンプル	中程度 (自動スクリプトあり)
対象ユーザ	基本的なPCB操作を必要とするユーザ	高度な機能を必要とするユーザ

サーバの選択

どちらのサーバを使用するかは、プロジェクトの要件によって異なる。

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

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

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

• 包括的なツールセットが必要な場合
• 回路図操作機能が必要な場合
• リアルタイムUI同期を使用したい場合
• Windows環境での使用を想定している場合
• JLCPCB統合等の将来的な機能拡張を期待する場合
• MCP 2025-06-18仕様への完全準拠が必要な場合

サーバ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プロジェクトファイルのバックアップを定期的に実施
• アクセスログの監視
• ツールのバージョン管理とドキュメントの維持

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

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

# 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-7.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の場所を確認する。

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

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

• RHEL / SUSE

  /usr/lib64/python3.x/site-packages/

• 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サーバが利用可能であることを確認する。

設定

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の実行、Gerberファイルの出力等) を提供する。
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:
    """Gerberファイルを出力する"""
    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"Gerberファイルを {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

  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プロジェクトをバックアップする。

 #!/usr/bin/env sh
 ## backup-kicad-projects.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)
 
 # 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トランスポートの場合、標準出力にログを出力していないか確認する。

Gerberファイルの出力に失敗する

• 出力ディレクトリの書き込み権限があるか確認する。
• ディスク容量が十分にあるか確認する。
• 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)}

外部リンク

• KiCAD公式サイト
• KiCADドキュメント
• KiCAD GitHubリポジトリ
• Model Context Protocol公式サイト
• lamaalrajih/kicad-mcp on Glama

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

概要

mixelpixx/KiCAD-MCP-Serverは、TypeScriptとPythonのハイブリッド実装による高度なKiCAD MCPサーバである。
MCP 2025-06-18仕様に完全準拠しており、52のツール、8のリソース、包括的なエラーハンドリング、クロスプラットフォーム対応を提供する。

主要な機能

• 52のツール

  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以上

  Python API (pcbnew) を含む

• Node.js 18以上
• Python 3.10以上
• 必須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

リポジトリをクローンしてビルドする。

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 11

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

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

  C:\Program Files\KiCad\9.0\lib\python3\dist-packages

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/9.0/lib/python3/dist-packages",
           "DEBUG": "mcp:*"
         },
         "transportType": "stdio"
       }
     }
   }
  

  
  

• プロジェクト固有のMCPサーバとして追加する場合

  プロジェクトディレクトリに .cursor/mcp.jsonファイルを作成

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

利用可能なツール

KiCAD-MCP-Serverは、52のツールを提供する。これらのツールは機能別に分類されている。

プロジェクト管理 (4ツール)

• create_project

  新しいKiCADプロジェクトを初期化する

• open_project

  既存のプロジェクトファイルを読み込む

• save_project

  現在のプロジェクト状態を保存する

• get_project_info

  プロジェクトのメタデータを取得する

ボード操作 (9ツール)

• 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

  テキスト注釈を追加する

コンポーネント配置 (10ツール)

• place_component

  フットプリントを指定して単一のコンポーネントを配置する

• move_component

  既存のコンポーネントを再配置する

• rotate_component

  コンポーネントを指定角度で回転する

• delete_component

  ボードからコンポーネントを削除する

• edit_component

  コンポーネントのプロパティを変更する

• get_component_properties

  コンポーネントの詳細を照会する

• get_component_list

  配置されたすべてのコンポーネントをリストする

• place_component_array

  コンポーネントのグリッド/パターンを作成する

• align_components

  複数のコンポーネントを整列する

• duplicate_component

  既存のコンポーネントをコピーする

ルーティングとネット (8ツール)

• add_net

  電気ネットを作成する

• route_trace

  銅箔トレースをルーティングする

• add_via

  レイヤー遷移用のビアを配置する

• delete_trace

  トレースを削除する

• get_nets_list

  すべてのネットをリストする

• create_netclass

  ルール付きのネットクラスを定義する

• add_copper_pour

  銅箔ゾーン/ポアを作成する

• route_differential_pair

  差動信号をルーティングする

ライブラリ管理 (4ツール)

• list_libraries

  利用可能なフットプリントライブラリをリストする

• search_footprints

  フットプリントを検索する

• list_library_footprints

  ライブラリ内のフットプリントをリストする

• get_footprint_info

  フットプリントの詳細を取得する

デザインルール (4ツール)

• set_design_rules

  DRCパラメータを設定する

• get_design_rules

  現在のルールを取得する

• run_drc

  デザインルールチェックを実行する

• get_drc_violations

  DRCエラーレポートを取得する

エクスポート (5ツール)

• export_gerber

  Gerber製造ファイルを生成する

• export_pdf

  PDFドキュメントをエクスポートする

• export_svg

  SVGベクターグラフィックスを作成する

• export_3d

  3Dモデルを生成する (STEP/VRML)

• export_bom

  部品表を作成する

回路図設計 (6ツール)

• create_schematic

  新しい回路図を初期化する

• load_schematic

  既存の回路図を開く

• add_schematic_component

  シンボルを配置する

• add_schematic_wire

  コンポーネントピンを接続する

• list_schematic_libraries

  シンボルライブラリをリストする

• export_schematic_pdf

  回路図PDFをエクスポートする

UI管理 (2ツール)

• check_kicad_ui

  KiCADが実行中かチェックする

• launch_kicad_ui

  KiCADアプリケーションを起動する

リソース

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フォルダにGerberファイルをエクスポートしてください。

IPC API統合 (実験的)

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

IPC APIの有効化

KiCADで IPC APIを有効化する。

Preferences > Plugins > Enable IPC API Server

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\\9.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バージョン、完全なエラーメッセージとスタックトレース、関連するログの抜粋

外部リンク

• GitHub Repository
• mixelpixx/KiCAD-MCP-Server on Glama
• KiCAD公式サイト
• Model Context Protocol公式サイト
• kicad-skip (回路図操作)