kicad-mcp-server/docs/FOOTPRINT_SYMBOL_CREATOR_GUIDE.md

Creating Custom Footprints and Symbols

Added in: v2.2.1-alpha (PRs #48, #49, contributor: @Kletternaut)

When existing KiCAD libraries don't have the component you need, these 8 tools let you create custom footprints and symbols programmatically. This enables automated part creation for custom PCB designs, specialized components, or rapid prototyping workflows where manual library editing would be time-consuming.

Part 1: Footprint Creator

Footprints define the physical copper pads, silkscreen markings, and courtyard boundaries for PCB components. The footprint creator tools generate .kicad_mod files inside .pretty library directories.

create_footprint

Create a new KiCAD footprint (.kicad_mod) inside a .pretty library directory. Supports SMD and THT pads, courtyard, silkscreen, and fab-layer rectangles.

Parameter	Type	Required	Description
libraryPath	string	Yes	Path to the .pretty library directory (created if missing). E.g. C:/MyProject/MyLib.pretty
name	string	Yes	Footprint name, e.g. 'R_0603_Custom'
description	string	No	Human-readable description
tags	string	No	Space-separated tag string, e.g. 'resistor SMD 0603'
pads	array	No	List of pad objects (see Pad Schema below). Can be empty for outlines-only footprints
courtyard	object	No	Courtyard rectangle on F.CrtYd (recommended: 0.25 mm clearance around pads)
silkscreen	object	No	Silkscreen rectangle on F.SilkS
fabLayer	object	No	Fab-layer rectangle on F.Fab (shows component body)
refPosition	object	No	Position of the REF** text, e.g. {x: 0, y: -1.27} (default: 0, -1.27)
valuePosition	object	No	Position of the Value text, e.g. {x: 0, y: 1.27} (default: 0, 1.27)
overwrite	boolean	No	Replace existing footprint file (default: false)

Pad Schema

Each pad object in the pads array supports:

Parameter	Type	Required	Description
number	string	Yes	Pad number / name, e.g. '1', '2', 'A1'
type	enum	Yes	Pad type: smd, thru_hole, or np_thru_hole
shape	enum	No	Pad shape: rect, circle, oval, or roundrect (default: rect for SMD, circle for THT)
at	object	Yes	Pad centre position: {x: number, y: number, angle?: number} in mm
size	object	Yes	Pad size: {w: number, h: number} in mm
drill	number or object	No	Round drill diameter (mm) or oval drill {w: number, h: number} (required for thru_hole pads)
layers	array	No	Override default layer list, e.g. ['F.Cu','F.Paste','F.Mask']
roundrect_ratio	number	No	Corner radius ratio for roundrect shape (0.0-0.5, default 0.25)

Rectangle Schema (courtyard, silkscreen, fabLayer)

Parameter	Type	Required	Description
x1	number	Yes	Left X in mm
y1	number	Yes	Top Y in mm
x2	number	Yes	Right X in mm
y2	number	Yes	Bottom Y in mm
width	number	No	Line width in mm

Pad Types

• SMD (smd): Surface-mount pads for components that sit on top of the PCB. Default layers: F.Cu, F.Paste, F.Mask
• THT (thru_hole): Through-hole pads for components with leads that pass through the PCB. Requires drill parameter. Default layers: *.Cu, F.Mask, B.Mask
• NPTH (np_thru_hole): Non-plated through-holes for mechanical mounting. Requires drill parameter. Default layers: *.Mask

edit_footprint_pad

Edit an existing pad inside a .kicad_mod footprint file. Updates size, position, drill, or shape without recreating the whole footprint.

Parameter	Type	Required	Description
footprintPath	string	Yes	Full path to the .kicad_mod file, e.g. C:/MyLib.pretty/R_Custom.kicad_mod
padNumber	string or number	Yes	Pad number to edit, e.g. '1' or 2
size	object	No	New pad size: {w: number, h: number} in mm
at	object	No	New pad position: {x: number, y: number, angle?: number} in mm
drill	number or object	No	New drill size: number (round) or {w: number, h: number} (oval) for THT pads
shape	enum	No	New pad shape: rect, circle, oval, or roundrect

When to use: Use this tool when you need to adjust an existing footprint's pad dimensions or positions without recreating the entire footprint. Useful for fine-tuning after initial creation or adapting existing footprints.

register_footprint_library

Register a .pretty footprint library in KiCAD's fp-lib-table so KiCAD can find the footprints. Run this after create_footprint when KiCAD shows 'library not found in footprint library table'.

Parameter	Type	Required	Description
libraryPath	string	Yes	Full path to the .pretty directory to register
libraryName	string	No	Nickname for the library in KiCAD (default: directory name without .pretty)
description	string	No	Optional description
scope	enum	No	project = writes fp-lib-table next to the .kicad_pro file (default); global = writes to the user's global KiCAD config
projectPath	string	No	Path to the .kicad_pro file or its directory (required for scope=project when the library is not in the project folder)

How fp-lib-table works: KiCAD maintains a table mapping library nicknames to filesystem paths. Project-scope tables (fp-lib-table in the project directory) take precedence over global tables. This allows project-specific libraries without polluting the global configuration.

list_footprint_libraries

List available .pretty footprint libraries and their contents (first 20 footprints per library). Searches KiCAD standard install paths by default.

Parameter	Type	Required	Description
searchPaths	array	No	Override default search paths. Each entry should be a directory that contains .pretty subdirs

Example: Creating a Custom SOT-23 Footprint

This example creates a simple 3-pad SMD footprint for a SOT-23 transistor package:

// Step 1: Create the footprint
{
  "libraryPath": "/home/user/myproject/CustomParts.pretty",
  "name": "SOT-23_Custom",
  "description": "SOT-23 3-pin SMD package, custom pitch",
  "tags": "SOT-23 transistor SMD",
  "pads": [
    {
      "number": "1",
      "type": "smd",
      "shape": "rect",
      "at": {"x": -0.95, "y": 1.0},
      "size": {"w": 0.6, "h": 0.7}
    },
    {
      "number": "2",
      "type": "smd",
      "shape": "rect",
      "at": {"x": 0.95, "y": 1.0},
      "size": {"w": 0.6, "h": 0.7}
    },
    {
      "number": "3",
      "type": "smd",
      "shape": "rect",
      "at": {"x": 0, "y": -1.0},
      "size": {"w": 0.6, "h": 0.7}
    }
  ],
  "courtyard": {
    "x1": -1.5,
    "y1": -1.5,
    "x2": 1.5,
    "y2": 1.5,
    "width": 0.05
  },
  "silkscreen": {
    "x1": -1.3,
    "y1": -0.3,
    "x2": 1.3,
    "y2": 0.3,
    "width": 0.12
  },
  "fabLayer": {
    "x1": -1.25,
    "y1": -0.25,
    "x2": 1.25,
    "y2": 0.25,
    "width": 0.1
  }
}

// Step 2: Register the library so KiCAD can find it
{
  "libraryPath": "/home/user/myproject/CustomParts.pretty",
  "scope": "project",
  "projectPath": "/home/user/myproject/myproject.kicad_pro"
}

The footprint will be saved as /home/user/myproject/CustomParts.pretty/SOT-23_Custom.kicad_mod and will be available in KiCAD's footprint browser under the library name "CustomParts".

Part 2: Symbol Creator

Symbols define the schematic representation of electronic components, including pins, graphical body shapes, and electrical properties. The symbol creator tools generate and manage .kicad_sym library files.

create_symbol

Create a new schematic symbol in a .kicad_sym library file (created if missing). After creation, use register_symbol_library so KiCAD finds it.

Pin positions are where the wire connects; the symbol body is drawn between them.

Coordinate tips:

• Body rectangle typically spans ±2.54 to ±5.08 mm
• Pins on left side: at.x = body_left - length, angle=0 (wire goes right)
• Pins on right side: at.x = body_right + length, angle=180 (wire goes left)
• Pins on top: at.y = body_top + length, angle=270 (wire goes down)
• Pins on bottom: at.y = body_bottom - length, angle=90 (wire goes up)
• Standard pin length: 2.54 mm, standard grid: 2.54 mm

Parameter	Type	Required	Description
libraryPath	string	Yes	Path to the .kicad_sym file (created if missing)
name	string	Yes	Symbol name, e.g. 'TMC2209', 'MyOpAmp'
referencePrefix	string	No	Schematic reference prefix: 'U' (IC), 'R' (resistor), 'J' (connector), etc. Default: 'U'
description	string	No	Human-readable description
keywords	string	No	Space-separated search keywords
datasheet	string	No	Datasheet URL or '~'
footprint	string	No	Default footprint, e.g. 'Package_SO:SOIC-8_3.9x4.9mm_P1.27mm'
inBom	boolean	No	Include in BOM (default true)
onBoard	boolean	No	Include in netlist for PCB (default true)
pins	array	No	List of pin objects (see Pin Schema below). Can be empty for graphical-only symbols
rectangles	array	No	Body rectangle(s). Typically one rectangle defining the IC body
polylines	array	No	Polyline graphics for custom body shapes (op-amp triangles, etc.)
overwrite	boolean	No	Replace existing symbol with same name (default false)

Pin Schema

Each pin object in the pins array supports:

Parameter	Type	Required	Description
name	string	Yes	Pin name, e.g. 'VCC', 'GND', 'IN+', '~' for unnamed
number	string or number	Yes	Pin number, e.g. '1', '2', 'A1'
type	enum	Yes	Electrical pin type (see Pin Types below)
at	object	Yes	Pin endpoint position: {x: number, y: number, angle: number} where angle is the direction the pin wire extends FROM the symbol body
length	number	No	Pin length in mm (default 2.54)
shape	enum	No	Pin graphic shape (default: line)

Pin angle conventions:

• 0 = right (wire extends to the right from the symbol body)
• 90 = up (wire extends upward)
• 180 = left (wire extends to the left)
• 270 = down (wire extends downward)

Pin Types (Electrical)

Type	Description
input	Input pin
output	Output pin
bidirectional	Bidirectional I/O
tri_state	Tri-state output
passive	Passive component (resistors, capacitors)
free	Free pin (no electrical rule checking)
unspecified	Unspecified type
power_in	Power input (VCC, VDD)
power_out	Power output (regulators)
open_collector	Open collector output
open_emitter	Open emitter output
no_connect	Not connected

Pin Shapes (Graphical)

Shape	Description
line	Standard pin (default)
inverted	Pin with inversion bubble
clock	Clock input (triangle)
inverted_clock	Inverted clock with bubble
input_low	Active-low input
clock_low	Active-low clock
output_low	Active-low output
falling_edge_clock	Falling edge triggered
non_logic	Non-logic pin

Rectangle Schema

Parameter	Type	Required	Description
x1	number	Yes	Left X in mm
y1	number	Yes	Top Y in mm
x2	number	Yes	Right X in mm
y2	number	Yes	Bottom Y in mm
width	number	No	Stroke width in mm (default 0.254)
fill	enum	No	Fill type: none, outline, or background (default: background)

Polyline Schema

Parameter	Type	Required	Description
points	array	Yes	List of XY points: [{x: number, y: number}, ...] in mm
width	number	No	Stroke width in mm (default 0.254)
fill	enum	No	Fill type: none, outline, or background

delete_symbol

Remove a symbol from a .kicad_sym library file.

Parameter	Type	Required	Description
libraryPath	string	Yes	Path to the .kicad_sym file
name	string	Yes	Symbol name to delete

list_symbols_in_library

List all symbol names in a .kicad_sym library file.

Parameter	Type	Required	Description
libraryPath	string	Yes	Path to the .kicad_sym file

register_symbol_library

Register a .kicad_sym library in KiCAD's sym-lib-table so symbols can be used in schematics. Run this after create_symbol when KiCAD shows 'library not found'.

Parameter	Type	Required	Description
libraryPath	string	Yes	Full path to the .kicad_sym file
libraryName	string	No	Nickname (default: file name without extension)
description	string	No	Optional description
scope	enum	No	project = writes sym-lib-table next to .kicad_pro (default); global = user config
projectPath	string	No	Path to .kicad_pro or its directory (for scope=project)

Example: Creating a Simple IC Symbol

This example creates a 4-pin IC symbol (VCC, GND, IN, OUT):

// Step 1: Create the symbol
{
  "libraryPath": "/home/user/myproject/CustomSymbols.kicad_sym",
  "name": "MyRegulator",
  "referencePrefix": "U",
  "description": "Simple voltage regulator",
  "keywords": "regulator power",
  "datasheet": "~",
  "footprint": "Package_TO_SOT_SMD:SOT-23",
  "pins": [
    {
      "name": "VIN",
      "number": "1",
      "type": "power_in",
      "at": {"x": -7.62, "y": 2.54, "angle": 0},
      "length": 2.54
    },
    {
      "name": "GND",
      "number": "2",
      "type": "power_in",
      "at": {"x": 0, "y": -7.62, "angle": 90},
      "length": 2.54
    },
    {
      "name": "VOUT",
      "number": "3",
      "type": "power_out",
      "at": {"x": 7.62, "y": 2.54, "angle": 180},
      "length": 2.54
    }
  ],
  "rectangles": [
    {
      "x1": -5.08,
      "y1": -5.08,
      "x2": 5.08,
      "y2": 5.08,
      "width": 0.254,
      "fill": "background"
    }
  ]
}

// Step 2: Register the library
{
  "libraryPath": "/home/user/myproject/CustomSymbols.kicad_sym",
  "scope": "project",
  "projectPath": "/home/user/myproject/myproject.kicad_pro"
}

Pin positioning explained:

• VIN pin at (-7.62, 2.54, angle=0): Wire extends to the right, so the symbol body should be to the right. Body left edge is at -5.08, and pin length is 2.54, so -7.62 = -5.08 - 2.54
• GND pin at (0, -7.62, angle=90): Wire extends upward, body bottom is at -5.08, so -7.62 = -5.08 - 2.54
• VOUT pin at (7.62, 2.54, angle=180): Wire extends to the left, body right is at 5.08, so 7.62 = 5.08 + 2.54

Coordinate Systems

Footprint Coordinates

• Origin (0, 0) is typically at the component center or pin 1
• Positive X extends right, positive Y extends down (PCB view from top)
• All dimensions in millimeters
• Courtyard should extend 0.25mm beyond pads for IPC-7351 compliance
• Silkscreen should not overlap pads (typically 0.1-0.2mm clearance)

Symbol Coordinates

• Origin (0, 0) is typically at the symbol center
• Positive X extends right, positive Y extends up (schematic convention)
• All dimensions in millimeters
• Standard grid is 2.54mm (100 mil) for pin spacing
• Pin positions define where wires connect, not where the pin graphic starts
• Body graphics are drawn independently of pin positions

Key Difference

Footprints use a "Y-down" coordinate system (like screen coordinates), while symbols use a "Y-up" coordinate system (like mathematical graphs). This is a KiCAD convention that matches industry standards for PCB layout vs schematic capture.

Integration with Design Workflow

Typical Workflow

1. Create the symbol using create_symbol with pin definitions and body graphics
2. Register the symbol library using register_symbol_library so it appears in the schematic editor
3. Create the footprint using create_footprint with pad definitions and courtyard
4. Register the footprint library using register_footprint_library so it appears in the PCB editor
5. Link symbol to footprint by setting the footprint parameter in create_symbol, or assign it later in the schematic editor

Library Organization

• Project-scope libraries: Store in the project directory, register with scope: "project". Best for project-specific custom parts.
• Global libraries: Store in a central location, register with scope: "global". Best for reusable parts across multiple projects.
• Naming conventions: Use descriptive names. For footprints: PackageType_Variant, e.g. SOIC-8_Custom. For symbols: PartNumber or FunctionDescription.

Validation

After creating custom parts:

• Open KiCAD schematic editor and verify the symbol appears in the "Add Symbol" dialog
• Check pin numbers, names, and electrical types in symbol properties
• Open KiCAD PCB editor and verify the footprint appears in the footprint browser
• Use the 3D viewer to check pad positions and courtyard clearances
• Run Design Rules Check (DRC) to ensure courtyard and clearance compliance

Source Files

• TypeScript tool definitions: /home/chris/MCP/KiCAD-MCP-Server/src/tools/footprint.ts
• TypeScript symbol definitions: /home/chris/MCP/KiCAD-MCP-Server/src/tools/symbol-creator.ts
• Python footprint implementation: /home/chris/MCP/KiCAD-MCP-Server/python/commands/footprint.py
• Python symbol implementation: /home/chris/MCP/KiCAD-MCP-Server/python/commands/symbol_creator.py