KiCad MCP SEA

KiCad PCB manufacturing audit via MCP + Ollama. IPC rules engine for SEA fabs.

KiCad MCP SEA is a Python server that audits KiCad PCB designs against South-East Asian (SEA) manufacturer capabilities. It combines an IPC-compatible DFM rules engine with an LLM (via Ollama) to generate actionable fabrication reports.

The server exposes 6 tools through the Model Context Protocol (MCP), making them accessible from Claude Desktop, VS Code Copilot, and any MCP-compatible client.

---

Architecture

graph TD
    Client[MCP Client<br/>Claude / VS Code / Custom]
    Server[kicad-mcp-sea server]
    BR[BoardReader<br/>KiCad IPC]
    DE[DFM Engine<br/>IPC Rules]
    FR[Fab Report Generator]
    FS[Fab Selector<br/>Formula Score]
    LC[LLM Client<br/>Ollama]
    FP[(Fab Profiles<br/>JSON)]
    DIST[(Distributor<br/>Catalogs)]
    KICAD[KiCad IPC API]
    OLLAMA[Ollama<br/>localhost:11434]

    Client -->|Streamable HTTP| Server
    Server --> BR
    Server --> DE
    Server --> FR
    Server --> FS
    Server --> LC
    Server -->|BOM crossref| DIST
    BR --> KICAD
    DE --> FP
    FR --> FP
    FS --> FP
    LC --> OLLAMA

Request Flow

sequenceDiagram
    participant C as MCP Client
    participant S as kicad-mcp-sea
    participant BR as BoardReader
    participant DE as DFMEngine
    participant FS as FabSelector
    participant LC as LLMClient
    participant KiCad
    participant Ollama

    Note over C,Ollama: analyze_board
    C->>S: analyze_board(board_path)
    S->>BR: read_board(path)
    BR->>KiCad: IPC get board data
    KiCad-->>BR: board metadata + DRC violations
    BR-->>S: board dict
    S-->>C: {"success": true, "data": {...}}

    Note over C,Ollama: run_dfm
    C->>S: run_dfm(board_path, fab_slug)
    S->>BR: read_board(path)
    S->>DE: run_dfm(board_data, fab_slug)
    DE->>DE: load fab profile & check rules
    DE-->>S: violations + verdicts
    S-->>C: {"success": true, "data": {...}}

    Note over C,Ollama: select_best_fab
    C->>S: select_best_fab(board_path, priorities)
    S->>BR: read_board(path)
    S->>FS: score fabs by compatibility
    FS->>FS: load all profiles & rank
    FS-->>S: ranked fab list
    S-->>C: {"success": true, "data": {...}}

    Note over C,Ollama: ai_review
    C->>S: ai_review(board_path, fab_slug, language)
    S->>BR: read_board(path)
    S->>DE: run_dfm(board_data, fab_slug)
    S->>LC: explain_violations_bulk(violations, lang)
    LC->>Ollama: POST /api/generate (GBNF grammar)
    Ollama-->>LC: structured JSON explanations
    LC-->>S: enriched violations
    S-->>C: {"success": true, "data": {report, ai_status}}

Data flows through a linear pipeline: board file to BoardReader (IPC) to DFMEngine (rule check) to FabReportGenerator (report). The LLMClient enriches violation explanations when Ollama is available. See docs/architecture.md for additional sequence diagrams and ADRs.

---

Quick Start

# 1. Install from PyPI
pip install kicad-mcp-sea

# 2. Start the MCP server
kicad-mcp-sea serve --host 127.0.0.1 --port 8080

# 3. Connect your MCP client

Step 3 means adding the server config to your MCP client. For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "kicad-mcp-sea": {
      "command": "kicad-mcp-sea",
      "args": ["serve", "--port", "8080"],
      "env": {}
    }
  }
}

See docs/usage.md for VS Code and other client configurations.

Prerequisites

• KiCad 8+ with IPC API enabled (Preferences > Plugins > API Server)
• Ollama (optional) for AI-enriched DFM review

---

Tools

All tools accept a dry_run parameter and return a consistent JSON envelope: {"success": bool, "data": ..., "error": ...}.

Tool	Description	Key Parameters
analyze_board	Parse a KiCad PCB file and extract design features	board_path (required)
run_dfm	Check a design against IPC-compatible DFM rules for a fab	board_path, fab_slug (both required)
generate_fab_report	Produce a structured fabrication report with DFM results and pricing	board_path, fab_slug, language
ai_review	Review a design using Ollama for manufacturability with AI explanations	board_path, fab_slug, language ("en" or "ms")
select_best_fab	Rank SEA fabs by board compatibility (formula-based scoring)	board_path, priorities (cost/quality/speed)
crossref_bom	Cross-reference BOM against distributor inventory (offline)	board_path, distributor ("gennex" or "all")

Dry Run Mode

Every tool supports dry_run=True. This returns a plan without executing:

{
  "success": true,
  "data": {
    "dry_run": true,
    "tool": "run_dfm",
    "would_read": "simple.kicad_pcb",
    "would_check_against": "guh",
    "description": "Run DFM checks against fab profile and return violations"
  }
}

Use dry run to validate tool parameters before touching KiCad or reading files.

---

Fab Profiles

A fab profile is a JSON file describing a PCB fabrication house: capabilities, DFM rules, pricing, and contact info. Profiles live in fabs/ and are auto-discovered. Adding a new fab is as simple as dropping a *.json file.

{
  "fab_name": "GUH PCB Sdn Bhd",
  "slug": "guh",
  "location": "Penang",
  "country": "Malaysia",
  "capabilities": {
    "max_layers": 6,
    "min_trace_mm": 0.2032,
    "min_space_mm": 0.2032,
    "min_drill_mm": 0.3,
    "min_annular_ring_mm": 0.15,
    "max_board_size_mm": [600, 600],
    "copper_weight_oz": [1, 2, 3]
  },
  "dfm_rules": [
    { "rule_name": "track_width", "severity": "error", "min": 0.2032, "unit": "mm" },
    { "rule_name": "clearance",   "severity": "error", "min": 0.2032, "unit": "mm" },
    { "rule_name": "drill_size",  "severity": "error", "min": 0.3,    "unit": "mm" },
    { "rule_name": "annular_width","severity": "warning","min": 0.15,  "unit": "mm" },
    { "rule_name": "copper_weight","severity": "info",   "min": 1, "max": 3, "unit": "oz" }
  ],
  "pricing": {
    "setup_cost": 120.0,
    "per_cm2_cost": 0.035,
    "min_order_qty": 5,
    "lead_time_days": 10
  },
  "contact": {
    "phone": "+604-616-6333",
    "email": "sales@guhpcb.com.my",
    "website": "https://www.guhpcb.com.my"
  }
}

To add a new fab: Create a JSON file in fabs/ named after the fab slug (e.g. fabs/jlpcb.json), fill in the fields, validate against fabs/schema.json, and commit. No code changes needed. See docs/fab-profiles.md for the full schema reference.

---

Requirements

• Python 3.11 or later
• KiCad 8+ with IPC API server enabled
• Ollama (optional) for LLM-backed DFM analysis
• OS: macOS, Linux (Windows via WSL)

---

FAQ

Does this work without KiCad running?

Yes, but in degraded mode. The analyze_board and run_dfm tools detect when KiCad is unreachable and return a warning with limited data. The server still starts and responds, but board data requires the KiCad IPC API. Tools that depend on board data (run_dfm, generate_fab_report, ai_review) return a "status": "skipped" response when KiCad is not running.

Can I use this with cloud LLMs?

Technically yes. Set OLLAMA_HOST to point at any OpenAI-compatible API endpoint. However, the server was designed for local, offline use. The GBNF grammars and prompt templates assume a local Ollama instance. Cloud API calls may introduce latency and data privacy concerns that the project does not address.

What file formats are supported?

Currently only KiCad PCB files (.kicad_pcb). The BoardReader uses the KiCad IPC API which expects KiCad's native board format. Other EDA formats (Altium, Eagle, OrCAD) are not supported. If you need support for other formats, consider opening a feature request.

Does this work without Ollama?

Yes. The analyze_board, run_dfm, generate_fab_report, select_best_fab, and crossref_bom tools work fully without Ollama. Only ai_review requires Ollama, and it falls back to rule-based recommendations with a warning if Ollama is unreachable.

Can I use it with non-SEA fabs?

Yes. The fab profile schema is generic. Profiles for non-SEA fabs work identically. Just create a JSON profile for any fab worldwide and the DFM engine and fab selector will use it.

What KiCad versions are supported?

KiCad 8+ with the IPC API plugin enabled. KiCad 9 and 10 are recommended for stable IPC support. KiCad 11+ adds native headless kicad-cli api-server support. See docs/architecture.md for version-specific notes.

Does the DFM engine modify my board files?

No. All KiCad IPC calls are read-only. The server never writes to .kicad_pcb files.

How do I add a new fab?

Create a JSON file in fabs/ following the schema in fabs/schema.json. See Fab Profiles above and docs/fab-profiles.md for the complete guide.

Does BOM cross-reference need internet?

No. Distributor catalogs are bundled as static JSON files. All matching is done offline with fuzzy string comparison. No API keys or network calls are needed.

What languages does the AI review support?

English ("en") and Bahasa Malaysia ("ms"). The Malay language support includes full DFM explanations and recommendations translated into Malaysian technical terminology. Add more languages by creating prompt templates in src/kicad_mcp_sea/prompts/.

Is this ready for production?

The project is in Alpha. The API and CLI are under active development. Breaking changes may occur between minor versions. Not yet recommended for production use.

---

Documentation

Document	Description
docs/architecture.md	Component diagrams, data flow, KiCad IPC notes, ADRs
docs/dfm-rules.md	DFM rule types, IPC standards mapping, examples
docs/usage.md	CLI examples, tool reference, MCP client configs
docs/fab-profiles.md	Fab profile schema, adding a new fab
CONTRIBUTING.md	Dev setup, code style, PR workflow

---

License

MIT. See LICENSE.

Project Links

• GitHub
• PyPI
• Issue Tracker