altium-designer-mcp

# altium-designer-mcp

[![CI](https://github.com/embedded-society/altium-designer-mcp/actions/workflows/ci_main.yml/badge.svg)](https://github.com/embedded-society/altium-designer-mcp/actions/workflows/ci_main.yml)
[![codecov](https://codecov.io/gh/embedded-society/altium-designer-mcp/branch/main/graph/badge.svg)](https://app.codecov.io/gh/embedded-society/altium-designer-mcp)

**Let an AI build your Altium libraries — it does the engineering, this tool writes the files.**

An MCP server that gives AI assistants (Claude Code, Claude Desktop, Cursor, Antigravity, VS Code Copilot — any MCP client) file I/O
and primitive-placement tools for Altium Designer `.PcbLib` (footprint) and `.SchLib` (symbol)
libraries — so the AI can create and maintain *any* component, not just pre-programmed packages.

---

## The Problem

Building Altium component libraries by hand is slow and repetitive — every footprint means
looking up IPC-7351B pad sizes, courtyards, and silkscreen, then placing each primitive by
hand. AI assistants are excellent at exactly that reasoning, but they **cannot write Altium's
binary `.PcbLib`/`.SchLib` files** — an undocumented OLE compound format that is easy to
corrupt, and Altium silently refuses to open a malformed file.

| Approach | Problem |
|----------|---------|
| Draw every footprint by hand in Altium | Slow and repetitive; the AI can't touch the file |
| Ask an AI to emit the binary file directly | It produces a corrupt file Altium won't open |
| Pre-programmed footprint generators | Only the package types someone coded in advance |

---

## The Core Idea

**The AI handles the intelligence. The tool handles file I/O.**

| Responsibility | Owner |
|---------------|-------|
| IPC-7351B calculations | AI |
| Package layout decisions | AI |
| Style choices | AI |
| Datasheet interpretation | AI |
| Reading/writing Altium files | This tool |
| Primitive placement | This tool |
| STEP model attachment | This tool |

This means the AI can create **any footprint** — not just pre-programmed package types.
See [docs/VISION.md](docs/VISION.md) for the full architectural rationale.

---

## Who Is This For?

Anyone who **builds or maintains Altium component libraries** and uses an **MCP-capable AI
assistant**. The AI does the engineering (datasheet → dimensions → style); this server lets it
read and write the actual `.PcbLib` / `.SchLib` files.

| If you… | Then… |
|---------|-------|
| Use Claude Code, Claude Desktop, Cursor, Antigravity, VS Code + Copilot — [any MCP client](docs/CLIENT_SETUP.md) — and design in Altium | ✅ This is for you |
| Want pre-baked generators for a fixed set of packages | ❌ Not this — the point is *any* component |
| Don't use Altium | ❌ Not applicable |

---

## Quick Start

> **[Client Setup](docs/CLIENT_SETUP.md)** — verified configuration for Claude Code, Claude
> Desktop, Google Antigravity, Cursor, VS Code, GitHub Copilot CLI, Windsurf, Cline, Roo Code,
> Kiro, JetBrains, Zed, Gemini CLI, Codex CLI, Continue, Goose, OpenCode and any other stdio
> MCP client, plus troubleshooting — on **Windows**, **Linux**, and **macOS**.
>
> **[Using the server](docs/USAGE.md)** — what to ask for once it is connected: example
> workflows, prompts and tips, identical for every client.

---

## How It Works

```text
┌─────────────────────────────────────────────────────────────────────────────┐
│  AI-ASSISTED COMPONENT CREATION                                             │
│                                                                             │
│  Engineer                    AI                         MCP Server          │
│    │                         │                              │               │
│    │  "Create 0603 resistor" │                              │               │
│    ├────────────────────────►│                              │               │
│    │                         │                              │               │
│    │                         │  AI reasons about:           │               │
│    │                         │  • IPC-7351B pad sizes       │               │
│    │                         │  • Courtyard margins         │               │
│    │                         │  • Silkscreen/symbol style   │               │
│    │                         │                              │               │
│    │                         │  write_pcblib(primitives)    │               │
│    │                         ├─────────────────────────────►│               │
│    │                         │                              │ Writes        │
│    │                         │                              │ .PcbLib +     │
│    │                         │  write_schlib(symbol)        │ .SchLib files │
│    │                         ├─────────────────────────────►│               │
│    │                         │◄─────────────────────────────┤               │
│    │                         │  { status: "success" }       │               │
│    │                         │                              │               │
│    │  "Done! Footprint       │                              │               │
│    │   and symbol created"   │                              │               │
│    │◄────────────────────────┤                              │               │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## MCP Tools

The server exposes **34 tools**, working on both `.PcbLib` (footprints) and
`.SchLib` (symbols). Every tool's full parameters and examples live in
**[docs/TOOLS.md](docs/TOOLS.md)** — this is the categorised overview.

### Read & write

| Tool | Purpose |
|------|---------|
| [`read_pcblib`](docs/TOOLS.md#read_pcblib) | Read footprints from a `.PcbLib`. |
| [`write_pcblib`](docs/TOOLS.md#write_pcblib) | Write footprints to a `.PcbLib`. |
| [`read_schlib`](docs/TOOLS.md#read_schlib) | Read symbols from a `.SchLib`. |
| [`write_schlib`](docs/TOOLS.md#write_schlib) | Write symbols to a `.SchLib`. |

### Inspect & visualise

| Tool | Purpose |
|------|---------|
| [`list_components`](docs/TOOLS.md#list_components) | List component names (paginated). |
| [`get_component`](docs/TOOLS.md#get_component) | Get one component's full data. |
| [`search_components`](docs/TOOLS.md#search_components) | Search across libraries by regex/glob. |
| [`component_exists`](docs/TOOLS.md#component_exists) | Check whether components exist. |
| [`render_footprint`](docs/TOOLS.md#render_footprint) | ASCII-art preview of a footprint. |
| [`render_symbol`](docs/TOOLS.md#render_symbol) | ASCII-art preview of a symbol. |
| [`extract_style`](docs/TOOLS.md#extract_style) | Extract styling from an existing library. |

### Compare

| Tool | Purpose |
|------|---------|
| [`diff_libraries`](docs/TOOLS.md#diff_libraries) | Compare two library files. |
| [`compare_components`](docs/TOOLS.md#compare_components) | Diff two specific components. |

### Edit in place

| Tool | Purpose |
|------|---------|
| [`update_component`](docs/TOOLS.md#update_component) | Update a component, preserving its position. |
| [`update_pad`](docs/TOOLS.md#update_pad) | Update one pad's properties. |
| [`update_primitive`](docs/TOOLS.md#update_primitive) | Update one primitive (track/arc/text/fill/region). |
| [`batch_update`](docs/TOOLS.md#batch_update) | Batch updates across all components. |
| [`reorder_components`](docs/TOOLS.md#reorder_components) | Reorder components in a library. |
| [`manage_schlib_parameters`](docs/TOOLS.md#manage_schlib_parameters) | List/get/set/remove SchLib parameters. |
| [`manage_schlib_footprints`](docs/TOOLS.md#manage_schlib_footprints) | Manage footprint links in SchLib symbols. |

### Manage components

| Tool | Purpose |
|------|---------|
| [`delete_component`](docs/TOOLS.md#delete_component) | Delete one or more components. |
| [`copy_component`](docs/TOOLS.md#copy_component) | Duplicate a component within a library. |
| [`rename_component`](docs/TOOLS.md#rename_component) | Rename a component (atomic). |
| [`copy_component_cross_library`](docs/TOOLS.md#copy_component_cross_library) | Copy a component to another library. |
| [`bulk_rename`](docs/TOOLS.md#bulk_rename) | Pattern-based multi-rename. |

### Library operations

| Tool | Purpose |
|------|---------|
| [`merge_libraries`](docs/TOOLS.md#merge_libraries) | Merge multiple libraries into one. |
| [`write_libpkg`](docs/TOOLS.md#write_libpkg) | Write a `.LibPkg` project grouping libraries for IntLib compilation. |
| [`export_library`](docs/TOOLS.md#export_library) | Export to JSON/CSV. |
| [`import_library`](docs/TOOLS.md#import_library) | Import from JSON (inverse of export). |
| [`validate_library`](docs/TOOLS.md#validate_library) | Validate for common issues. |
| [`repair_library`](docs/TOOLS.md#repair_library) | Remove orphaned data. |
| [`extract_step_model`](docs/TOOLS.md#extract_step_model) | Extract embedded STEP 3D models. |

### Backups & safety

| Tool | Purpose |
|------|---------|
| [`list_backups`](docs/TOOLS.md#list_backups) | List automatic backups. |
| [`restore_backup`](docs/TOOLS.md#restore_backup) | Restore from a backup. |

## Primitive Types

### Footprint Primitives (PcbLib)

| Primitive | Description |
|-----------|-------------|
| **Pad** | SMD or through-hole pad with designator, position, size, shape, layer (see Pad Shapes below) |
| **Via** | Vertical interconnect with layer span, hole size, and thermal relief |
| **Track** | Line segment on any layer (silkscreen, assembly, etc.) |
| **Arc** | Arc or circle on any layer |
| **Region** | Filled polygon (courtyard, copper pour) |
| **Text** | Text string with font, size, position, layer |
| **Fill** | Filled rectangle on any layer |
| **ComponentBody** | 3D model reference (embedded STEP models) |

#### Pad Shapes and Pin 1 Indicator

The `shape` property on pads controls the copper shape. Use this to indicate pin 1:

| Shape