kicad-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

KiCad MCP is a Model Context Protocol (MCP) server designed to automate KiCad PCB design tasks through natural language and API endpoints. Built on FastMCP, it provides LLM-driven automation for PCB design, DRC cleanup, BOM generation, 3D rendering, and cost analysis.

The goal is to enable commands like:

• "Generate a 4-layer PCB for an ESP32 dev board with USB-C power"
• "Fix all unconnected nets and rebalance copper fills"
• "Render a realistic 3D model with silkscreen and component textures"
• "Estimate production cost for 100 units via JLCPCB"

Development Commands

# Install dependencies
npm install  # or bun install, yarn, pnpm

# Run the stdio server (for CLI/local use with Claude Desktop)
npm start
npm run dev  # with auto-reload

# Run the HTTP server (for web/network use)
npm run start:http
npm run dev:http  # with auto-reload

# Build for production
npm run build        # builds stdio server to build/index.js
npm run build:http   # builds HTTP server to build/http-server.js
npm run prepublishOnly  # builds both

# Versioning and release
npm run version:patch
npm run version:minor
npm run version:major
npm run release

# Generate changelog
npm run changelog
npm run changelog:latest

Architecture

Core Structure

The server follows a modular FastMCP architecture with three main registration points:

1. Tools (src/core/tools.ts) — Executable MCP tools that perform actions
2. Resources (src/core/resources.ts) — Data resources accessible via URI templates
3. Prompts (src/core/prompts.ts) — Pre-defined prompt templates for LLM interactions

All three are registered in src/server/server.ts during server initialization.

Entry Points

• stdio mode: src/index.ts — Creates server and starts stdio transport
• HTTP mode: src/server/http-server.ts — Creates server and starts HTTP/SSE transport