altium-designer-mcp

An AI-operated Altium Designer libraries editor.

An MCP server that provides file I/O and primitive placement tools, enabling AI assistants
(Claude Code, Claude Desktop, VSCode Copilot) to create and manage Altium Designer
component libraries.

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 for the full architectural rationale.

Quick Start with Claude Code

Claude Code Setup Guide — Complete step-by-step instructions
for using this MCP server with Claude Code CLI on Windows, Linux, and macOS.

How It Works

┌─────────────────────────────────────────────────────────────────────────────┐
│  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 │
│    │                         ├─────────────────────────────►│               │
│    │                         │◄─────────────────────────────┤               │
│    │                         │  { success: true }           │               │
│    │                         │                              │               │
│    │  "Done! Footprint       │                              │               │
│    │   and symbol created"   │                              │               │
│    │◄────────────────────────┤                              │               │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

MCP Tools

`read_pcblib`

Read footprints from an Altium .PcbLib file. All coordinates are in millimetres.

{
    "name": "read_pcblib",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib"
    }
}

Pagination options (for large libraries):

{
    "name": "read_pcblib",
    "arguments": {
        "filepath": "./LargeLibrary.PcbLib",
        "component_name": "RESC1608X55N",
        "limit": 10,
        "offset": 0,
        "compact": true
    }
}

Parameter	Description
`component_name`	Fetch only this specific footprint
`limit`	Maximum footprints to return
`offset`	Skip first N footprints
`compact`	Omit redundant per-layer pad data when uniform (default: `true`)

`write_pcblib`

Write footprints to an Altium .PcbLib file. The AI provides primitive definitions.

{
    "name": "write_pcblib",
    "arguments": {
        "filepath": "./Passives.PcbLib",
        "footprints": [{
            "name": "RESC1608X55N",
            "description": "Chip resistor, 0603 (1608 metric)",
            "pads": [
                { "designator": "1", "x": -0.75, "y": 0, "width": 0.9, "height": 0.95 },
                { "designator": "2", "x": 0.75, "y": 0, "width": 0.9, "height": 0.95 }
            ],
            "tracks": [
                { "x1": -0.8, "y1": -0.425, "x2": 0.8, "y2": -0.425, "width": 0.12, "layer": "Top Overlay" },
                { "x1": -0.8, "y1": 0.425, "x2": 0.8, "y2": 0.425, "width": 0.12, "layer": "Top Overlay" }
            ],
            "regions": [
                { "vertices": [{"x": -1.45, "y": -0.73}, {"x": 1.45, "y": -0.73}, {"x": 1.45, "y": 0.73}, {"x": -1.45, "y": 0.73}], "layer": "Top Courtyard" }
            ]
        }],
        "append": false
    }
}

Parameter	Description
`append`	If `true`, add footprints to existing file; if `false`, create new file (default: `false`)

`read_schlib`

Read symbols from an Altium .SchLib file. Coordinates are in schematic units (10 units = 1 grid).

{
    "name": "read_schlib",
    "arguments": {
        "filepath": "./MySymbols.SchLib"
    }
}

Pagination options (for large libraries):

{
    "name": "read_schlib",
    "arguments": {
        "filepath": "./LargeLibrary.SchLib",
        "component_name": "RES_0603",
        "limit": 10,
        "offset": 0
    }
}

`write_schlib`

Write symbols to an Altium .SchLib file. The AI provides primitive definitions.

{
    "name": "write_schlib",
    "arguments": {
        "filepath": "./MySymbols.SchLib",
        "symbols": [...],
        "append": false
    }
}

Parameter	Description
`append`	If `true`, add symbols to existing file; if `false`, create new file (default: `false`)

Symbol properties:

Property	Description
`name`	Symbol name (required)
`description`	Symbol description
`designator_prefix`	Designator prefix (e.g., "R", "U", "C")
`part_count`	Number of parts for multi-part symbols (default: 1)
`pins`	Array of pin definitions

Pin properties:

Property	Description
`designator`	Pin number (required)
`name`	Pin name (required)
`x`, `y`	Position in schematic units (required)
`length`	Pin length (required)
`orientation`	`left`, `right`, `up`, `down` (required)
`electrical_type`	`input`, `output`, `bidirectional`, `passive`, `power`
`owner_part_id`	Part number for multi-part symbols (1-based, default: 1)
`symbol_inner_edge`	Pin symbol at inner edge: `none`, `dot`, `clock`, `schmitt`, etc.
`symbol_outer_edge`	Pin symbol at outer edge: `none`, `dot`, `active_low_input`, etc.
`symbol_inside`	Pin symbol inside: `none`, `dot`, `clock`, etc.
`symbol_outside`	Pin symbol outside: `none`, `dot`, `clock`, etc.

`list_components`

List component names in an Altium library file. Supports pagination for large libraries.

{
    "name": "list_components",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "limit": 50,
        "offset": 0,
        "include_metadata": true
    }
}

Parameter	Required	Description
`filepath`	Yes	Path to the library file
`limit`	No	Maximum number of components to return (default: all)
`offset`	No	Number of components to skip (default: 0)
`include_metadata`	No	Include component metadata like pad/pin counts (default: `false`)

Response includes:

total_count: Total number of components in the library
returned_count: Number of components in this response
offset: Current offset
has_more: Whether more components are available

With include_metadata: true (PcbLib):

{
    "components": [
        { "name": "RESC0603", "pad_count": 2, "track_count": 4, "has_3d_model": true }
    ]
}

With include_metadata: true (SchLib):

{
    "components": [
        { "name": "RESISTOR", "part_count": 1, "pin_count": 2, "footprint_count": 1 }
    ]
}

`extract_style`

Extract styling information from an existing library.

{
    "name": "extract_style",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib"
    }
}

Returns statistics about track widths, pad shapes, pin lengths, colours, and layer usage.

`delete_component`

Delete one or more components from an Altium library file. Works with both .PcbLib and .SchLib files.
Use dry_run=true to preview changes without modifying the file.

{
    "name": "delete_component",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "component_names": ["OLD_FOOTPRINT", "UNUSED_COMPONENT"],
        "dry_run": false
    }
}

Parameter	Description
`component_names`	Array of component names to delete
`dry_run`	If `true`, show what would be deleted without modifying the file (default: `false`)

Returns per-component status (deleted or not_found) and updated component counts.

A backup is automatically created before deletion (see Automatic Backups).

`validate_library`

Validate an Altium library file for common issues. Works with both .PcbLib and .SchLib files.

{
    "name": "validate_library",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib"
    }
}

Checks for:

Empty components (no pads/pins)
Duplicate designators within a component
Invalid coordinates (NaN, Infinity)
Zero or negative dimensions
Missing body graphics (SchLib)

Returns status (valid, warnings, or invalid) with a list of issues found.

`export_library`

Export an Altium library to JSON or CSV format for version control, backup, or external processing.

{
    "name": "export_library",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "format": "json",
        "compact": true
    }
}

Parameter	Description
`format`	Export format: `json` for full data, `csv` for summary table
`compact`	Omit redundant per-layer pad data when uniform (default: `true`)

JSON format returns complete component data including all primitives.

CSV format returns a summary table with columns: name, description, pad/pin count, etc.

`extract_step_model`

Extract embedded STEP 3D models from an Altium .PcbLib file. Models are stored compressed inside the library;
this tool extracts them to standalone .step files. Supports multiple extraction modes and pagination.

{
    "name": "extract_step_model",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "output_path": "./extracted_model.step",
        "model": "RESC1005X04L.step",
        "mode": "auto"
    }
}

Parameter	Required	Description
`filepath`	Yes	Path to the .PcbLib file containing embedded 3D models
`output_path`	No	Path where the extracted .step file will be saved. If omitted, returns base64-encoded data.
`model`	No	Model name (e.g., `RESC1005X04L.step`) or GUID to extract. If omitted and only one model exists, extracts it automatically. If multiple models exist and no model specified, lists available models.
`mode`	No	Extraction mode: `auto` (default), `list`, `extract_all`, `extract_by_footprint`
`footprint_name`	No	Footprint name (required for `extract_by_footprint` mode)
`limit`	No	Maximum number of models to list (default: all)
`offset`	No	Number of models to skip when listing (default: 0)

Extraction Modes:

Mode	Description
`auto`	Default behaviour — extract single model, or list if multiple exist
`list`	List all available models without extracting
`extract_all`	Extract all models to a directory (requires `output_path` to be a directory)
`extract_by_footprint`	Extract models used by a specific footprint (requires `footprint_name`)

Response (listing models):

{
    "status": "list",
    "filepath": "./MyLibrary.PcbLib",
    "message": "Multiple models found. Specify 'model' parameter with name or ID to extract.",
    "total_count": 50,
    "returned_count": 10,
    "offset": 0,
    "has_more": true,
    "models": [
        { "id": "{GUID...}", "name": "model1.step", "size_bytes": 12345 },
        { "id": "{GUID...}", "name": "model2.step", "size_bytes": 67890 }
    ]
}

Response (extraction success):

{
    "status": "success",
    "filepath": "./MyLibrary.PcbLib",
    "output_path": "./extracted_model.step",
    "model_id": "{GUID...}",
    "model_name": "RESC1005X04L.step",
    "size_bytes": 12345,
    "message": "STEP model extracted to './extracted_model.step'"
}

`import_library`

Import components into an Altium library from JSON data. This is the inverse of export_library —
it accepts the same JSON format that export_library produces, enabling round-trip workflows.

{
    "name": "import_library",
    "arguments": {
        "output_path": "./NewLibrary.PcbLib",
        "json_data": {
            "file_type": "PcbLib",
            "footprints": [...]
        },
        "append": false
    }
}

Parameter	Description
`output_path`	Path for the output library file (.PcbLib or .SchLib)
`json_data`	JSON object containing the library data (same format as `export_library` output)
`append`	If `true`, add components to existing file; if `false`, create new file (default: `false`)

JSON format (PcbLib):

{
    "file_type": "PcbLib",
    "footprints": [
        {
            "name": "RESC1608X55N",
            "description": "Chip resistor, 0603",
            "pads": [...],
            "tracks": [...],
            "regions": [...]
        }
    ]
}

JSON format (SchLib):

{
    "file_type": "SchLib",
    "symbols": [
        {
            "name": "RESISTOR",
            "description": "Generic resistor",
            "pins": [...]
        }
    ]
}

The library type is determined from:

The file_type field in the JSON data (preferred)
The output file extension (.PcbLib or .SchLib)

Use cases:

Round-trip editing: export → modify JSON → import
Version control: store libraries as JSON, import when needed
Migration: convert between formats or merge data from external sources
Backup restoration: recreate libraries from JSON backups

`diff_libraries`

Compare two Altium library files and report differences. Both files must be the same type.

{
    "name": "diff_libraries",
    "arguments": {
        "filepath_a": "./OldLibrary.PcbLib",
        "filepath_b": "./NewLibrary.PcbLib"
    }
}

Parameter	Description
`filepath_a`	Path to the first (base/old) library
`filepath_b`	Path to the second (new/changed) library

Returns:

added: Components in B but not in A
removed: Components in A but not in B
modified: Components in both with changes (count differences, description changes)

`batch_update`

Perform batch updates across all components in an Altium library file. Supports PcbLib
operations (track width updates, layer renames) and SchLib operations (parameter updates).

{
    "name": "batch_update",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "operation": "update_track_width",
        "parameters": {
            "from_width": 0.2,
            "to_width": 0.25,
            "tolerance": 0.001
        }
    }
}

Parameter	Description
`filepath`	Path to the PcbLib or SchLib file
`operation`	One of: `update_track_width`, `rename_layer`, `update_parameters`
`parameters`	Operation-specific parameters

PcbLib Operations:

Operation	Parameters	Description
`update_track_width`	`from_width`, `to_width`, `tolerance`	Update all tracks matching `from_width` (±tolerance) to `to_width`
`rename_layer`	`from_layer`, `to_layer`	Change all primitives from one layer to another

SchLib Operations:

Operation	Parameters	Description
`update_parameters`	`param_name`, `param_value`, `symbol_filter`?, `add_if_missing`?	Update parameter values across symbols

Example: Rename layer (PcbLib)

{
    "name": "batch_update",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "operation": "rename_layer",
        "parameters": {
            "from_layer": "Mechanical 1",
            "to_layer": "Mechanical 2"
        }
    }
}

Layer names accept both spaced format (Top Layer) and camelCase (TopLayer).

Example: Update parameters across symbols (SchLib)

{
    "name": "batch_update",
    "arguments": {
        "filepath": "./MySymbols.SchLib",
        "operation": "update_parameters",
        "parameters": {
            "param_name": "Manufacturer",
            "param_value": "Acme Corp",
            "symbol_filter": "^RES.*",
            "add_if_missing": true
        }
    }
}

Parameter	Description
`param_name`	Name of the parameter to update
`param_value`	New value for the parameter
`symbol_filter`	Optional regex to filter which symbols to update
`add_if_missing`	If true, add the parameter to symbols that don't have it (default: false)

`copy_component`

Copy/duplicate a component within an Altium library file. Creates a new component with a
different name but identical primitives. Useful for creating variants.

{
    "name": "copy_component",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "source_name": "RESC0603_IPC_MEDIUM",
        "target_name": "RESC0603_IPC_MEDIUM_V2",
        "description": "0603 resistor variant 2"
    }
}

Parameter	Description
`filepath`	Path to the library file (.PcbLib or .SchLib)
`source_name`	Name of the component to copy
`target_name`	Name for the new copied component
`description`	Optional description for the new component

Returns the new component count after copying.

`rename_component`

Rename a component within an Altium library file. This is an atomic operation that changes
the component's name while preserving all primitives and properties. More efficient than
copy + delete for simple renames.

{
    "name": "rename_component",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "old_name": "RESC0603_OLD",
        "new_name": "RESC0603_NEW"
    }
}

Parameter	Description
`filepath`	Path to the library file (.PcbLib or .SchLib)
`old_name`	Current name of the component to rename
`new_name`	New name for the component

Returns the component count after renaming (unchanged).

`copy_component_cross_library`

Copy a component from one Altium library to another. Both libraries must be the same type
(PcbLib to PcbLib, or SchLib to SchLib). Useful for consolidating libraries or sharing
components between projects.

{
    "name": "copy_component_cross_library",
    "arguments": {
        "source_filepath": "./SourceLibrary.PcbLib",
        "target_filepath": "./TargetLibrary.PcbLib",
        "component_name": "RESC0603_IPC_MEDIUM",
        "new_name": "RESC0603_COPIED",
        "description": "Copied from SourceLibrary",
        "ignore_missing_models": false,
        "preserve_external_paths": false
    }
}

Parameter	Description
`source_filepath`	Path to the source library file (.PcbLib or .SchLib)
`target_filepath`	Path to the target library file (must be same type as source)
`component_name`	Name of the component to copy from the source library
`new_name`	Optional new name for the component in the target library (defaults to original name)
`description`	Optional new description for the component (defaults to original description)
`ignore_missing_models`	If `true`, copy the component even if referenced embedded 3D models are missing (PcbLib only). The component body references will be removed. (default: `false`)
`preserve_external_paths`	If `true`, keep external 3D model file path references (default: `false` — external paths are removed as they are not portable)

Behaviour:

If the target file does not exist, it will be created
If the target file exists, the component will be added to it
If a component with the same name already exists in the target, an error is returned
Embedded 3D models are copied along with the component (if present and valid)
External STEP file references are removed by default (paths are not portable); use preserve_external_paths: true to keep them

`merge_libraries`

Merge multiple Altium libraries into a single library. All source libraries must be the same
type (all PcbLib or all SchLib). Components are copied from each source into the target library.

{
    "name": "merge_libraries",
    "arguments": {
        "source_filepaths": [
            "./LibraryA.PcbLib",
            "./LibraryB.PcbLib",
            "./LibraryC.PcbLib"
        ],
        "target_filepath": "./MergedLibrary.PcbLib",
        "on_duplicate": "skip"
    }
}

Parameter	Description
`source_filepaths`	Array of paths to source library files (.PcbLib or .SchLib)
`target_filepath`	Path to the target library file (will be created or appended to)
`on_duplicate`	How to handle duplicate names: `skip` (ignore), `error` (fail), `rename` (auto-suffix). Default: `error`

Behaviour:

If the target file does not exist, it will be created
If the target file exists, components will be appended to it
Duplicate handling options:
- error: Fail immediately if a duplicate is found (default)
- skip: Silently ignore duplicates, keeping the first occurrence
- rename: Auto-rename duplicates with _1, _2, etc. suffixes

Example Response:

{
    "status": "success",
    "target_filepath": "./MergedLibrary.PcbLib",
    "file_type": "PcbLib",
    "sources_count": 3,
    "merged_count": 45,
    "skipped_count": 2,
    "renamed_count": 0,
    "final_count": 45,
    "message": "Merged 45 components from 3 sources into './MergedLibrary.PcbLib' (total: 45)"
}

`reorder_components`

Reorder components in an Altium library file (.PcbLib or .SchLib). Specify the desired order as
a list of component names. Components not in the list are placed at the end in their original
relative order.

{
    "name": "reorder_components",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "component_order": ["RESC1608X55N", "RESC0805X40N", "RESC0402X20N"]
    }
}

Parameter	Description
`filepath`	Path to the .PcbLib or .SchLib file
`component_order`	Component names in desired order

Behaviour:

Components listed in component_order appear first, in the specified order
Components not in the list are appended at the end in their original relative order
Names in component_order that don't exist in the library are ignored

Example Response:

{
    "status": "success",
    "filepath": "./MyLibrary.PcbLib",
    "component_count": 5,
    "original_order": ["CAPC0402X20N", "RESC1608X55N", "RESC0805X40N", "RESC0402X20N", "INDC1005X55N"],
    "new_order": ["RESC1608X55N", "RESC0805X40N", "RESC0402X20N", "CAPC0402X20N", "INDC1005X55N"],
    "not_in_library": [],
    "appended_at_end": ["CAPC0402X20N", "INDC1005X55N"],
    "message": "Reordered 5 components in './MyLibrary.PcbLib' (2 components appended at end)"
}

`update_component`

Update a component in-place within an Altium library file, preserving its position. For PcbLib
files, provide a footprint object. For SchLib files, provide a symbol object. The component
is matched by the component_name parameter.

{
    "name": "update_component",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "component_name": "RESC0402X20N",
        "footprint": {
            "name": "RESC0402X20N",
            "description": "Updated resistor 0402",
            "pads": [
                {"designator": "1", "x": -0.5, "y": 0, "width": 0.5, "height": 0.5, "layer": "TopLayer"},
                {"designator": "2", "x": 0.5, "y": 0, "width": 0.5, "height": 0.5, "layer": "TopLayer"}
            ]
        }
    }
}

Parameter	Description
`filepath`	Path to the .PcbLib or .SchLib file
`component_name`	Name of the component to update (must exist)
`footprint`	For PcbLib: footprint data (same format as `write_pcblib`)
`symbol`	For SchLib: symbol data (same format as `write_schlib`)

Example Response:

{
    "status": "success",
    "filepath": "./MyLibrary.PcbLib",
    "file_type": "PcbLib",
    "component_name": "RESC0402X20N",
    "new_name": "RESC0402X20N",
    "renamed": false,
    "component_count": 5,
    "message": "Updated component 'RESC0402X20N' in './MyLibrary.PcbLib'"
}

`search_components`

Search for components across multiple Altium libraries using regex or glob patterns. Returns
matching component names with their source library paths. Supports both .PcbLib (footprints)
and .SchLib (symbols) files.

{
    "name": "search_components",
    "arguments": {
        "filepaths": [
            "./Resistors.PcbLib",
            "./Capacitors.PcbLib",
            "./ICs.PcbLib"
        ],
        "pattern": "SOIC-*",
        "pattern_type": "glob"
    }
}

Parameter	Description
`filepaths`	Array of library file paths to search (.PcbLib or .SchLib)
`pattern`	Search pattern to match component names
`pattern_type`	Pattern type: `glob` (wildcards like `*` and `?`) or `regex`. Default: `glob`

Glob Patterns:

* matches any number of characters
? matches a single character
Search is case-insensitive

Example Response:

{
    "status": "success",
    "pattern": "SOIC-*",
    "pattern_type": "glob",
    "libraries_searched": 3,
    "components_searched": 150,
    "matches_found": 5,
    "matches": [
        { "name": "SOIC-8", "library": "./ICs.PcbLib", "type": "PcbLib" },
        { "name": "SOIC-14", "library": "./ICs.PcbLib", "type": "PcbLib" },
        { "name": "SOIC-16", "library": "./ICs.PcbLib", "type": "PcbLib" }
    ],
    "message": "Found 5 matches for 'SOIC-*' across 3 libraries (150 components searched)"
}

`get_component`

Get a single component by name from an Altium library. Returns the full component data
(footprint or symbol) without needing to read and filter the entire library. Supports both
.PcbLib (footprints) and .SchLib (symbols) files.

{
    "name": "get_component",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "component_name": "SOIC-8"
    }
}

Parameter	Description
`filepath`	Path to the Altium library file (.PcbLib or .SchLib)
`component_name`	Exact name of the component to retrieve

Example Response (PcbLib):

{
    "status": "success",
    "filepath": "./MyLibrary.PcbLib",
    "component_name": "SOIC-8",
    "type": "PcbLib",
    "units": "mm",
    "component": {
        "name": "SOIC-8",
        "description": "8-pin SOIC package",
        "pads": [...],
        "tracks": [...]
    },
    "message": "Retrieved footprint 'SOIC-8' from './MyLibrary.PcbLib'"
}

Error Response (component not found):

{
    "isError": true,
    "content": [{
        "type": "text",
        "text": "Component 'SOIC-99' not found in library. Available components: SOIC-8, SOIC-14, SOIC-16 ... and 5 more"
    }]
}

`compare_components`

Compare two specific components in detail, showing differences in primitives, parameters, and
properties. Components can be from the same library or different libraries. Returns detailed
primitive-level differences (pads, tracks, pins, etc.).

{
    "name": "compare_components",
    "arguments": {
        "filepath_a": "./LibraryA.PcbLib",
        "component_a": "RESC0603_V1",
        "filepath_b": "./LibraryB.PcbLib",
        "component_b": "RESC0603_V2",
        "include_geometry": true,
        "tolerance": 0.001
    }
}

Parameter	Description
`filepath_a`	Path to the first library file (.PcbLib or .SchLib)
`component_a`	Name of the first component
`filepath_b`	Path to the second library file (can be same as `filepath_a`)
`component_b`	Name of the second component
`include_geometry`	Include detailed geometry comparisons (default: `true`)
`tolerance`	Tolerance for floating-point comparisons in mm (default: `0.001`)

Example Response:

{
    "status": "different",
    "summary": {
        "identical": false,
        "pad_differences": 2,
        "track_differences": 1,
        "description_changed": true
    },
    "differences": {
        "pads": [
            { "designator": "1", "field": "width", "a": 0.9, "b": 1.0 }
        ]
    }
}

`render_footprint`

Render an ASCII art visualisation of a footprint from a PcbLib file. Shows pads, tracks,
and other primitives in a simple text format for quick preview.

{
    "name": "render_footprint",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "component_name": "RESC0603_IPC_MEDIUM",
        "scale": 2.0,
        "max_width": 80,
        "max_height": 40
    }
}

Parameter	Description
`filepath`	Path to the PcbLib file
`component_name`	Name of the footprint to render
`scale`	Characters per mm (default: 2.0)
`max_width`	Maximum width in characters (default: 80)
`max_height`	Maximum height in characters (default: 40)

Returns ASCII art with pad designators shown in full (e.g., "1", "10", "A01"). Legend: # = pad area, - = track, o = arc, + = origin.

`render_symbol`

Render an ASCII art visualisation of a schematic symbol from a SchLib file. Shows pins,
rectangles, lines, and other primitives in a simple text format for quick preview.

{
    "name": "render_symbol",
    "arguments": {
        "filepath": "./MyLibrary.SchLib",
        "component_name": "LM358",
        "scale": 1.0,
        "max_width": 80,
        "max_height": 40,
        "part_id": 1
    }
}

Parameter	Description
`filepath`	Path to the SchLib file
`component_name`	Name of the symbol to render
`scale`	Characters per 10 schematic units (default: 1.0)
`max_width`	Maximum width in characters (default: 80)
`max_height`	Maximum height in characters (default: 40)
`part_id`	Part ID for multi-part symbols (default: 1, use 0 for all parts)

Returns ASCII art with pin designators shown in full (e.g., "1", "10", "VCC"). Legend: |-+ = rectangle, ~ = pin line, o = arc, O = ellipse, + = origin.

`manage_schlib_parameters`

Manage component parameters in Altium SchLib files. Supports listing, getting, setting,
adding, and deleting parameters like Value, Manufacturer, Part Number, etc.

{
    "name": "manage_schlib_parameters",
    "arguments": {
        "filepath": "./MyLibrary.SchLib",
        "component_name": "LM358",
        "operation": "set",
        "parameter_name": "Value",
        "value": "LM358D"
    }
}

Parameter	Description
`filepath`	Path to the SchLib file
`component_name`	Name of the symbol
`operation`	Operation: `list`, `get`, `set`, `add`, `delete`
`parameter_name`	Parameter name (required for get/set/add/delete)
`value`	Parameter value (required for set/add)
`hidden`	Whether parameter is hidden (optional for set/add)
`x`, `y`	Position in schematic units (optional for add)

Operations:

Operation	Description
`list`	Returns all parameters for a symbol
`get`	Returns a single parameter by name
`set`	Updates an existing parameter's value
`add`	Creates a new parameter
`delete`	Removes a parameter

`manage_schlib_footprints`

Manage footprint links in Altium SchLib symbols. Supports listing, adding, and removing
footprint references that link schematic symbols to PCB footprints.

{
    "name": "manage_schlib_footprints",
    "arguments": {
        "filepath": "./MyLibrary.SchLib",
        "component_name": "LM358",
        "operation": "add",
        "footprint_name": "SOIC-8_3.9x4.9mm"
    }
}

Parameter	Description
`filepath`	Path to the SchLib file
`component_name`	Name of the symbol
`operation`	Operation: `list`, `add`, `remove`
`footprint_name`	Footprint name (required for add/remove)
`description`	Footprint description (optional for add)

Operations:

Operation	Description
`list`	Returns all linked footprints for a symbol
`add`	Links a new footprint to the symbol
`remove`	Removes a footprint link from the symbol

`repair_library`

Repair a library file by removing orphaned data. For PcbLib files, this removes component body
references that point to non-existent embedded STEP models. This fixes libraries where 3D model
data was corrupted or incompletely deleted.

{
    "name": "repair_library",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "dry_run": true
    }
}

Parameter	Description
`filepath`	Path to the library file (.PcbLib)
`dry_run`	If `true`, report what would be removed without modifying the file (default: `false`)

Example Response:

{
    "library_type": "PcbLib",
    "footprints_checked": 5,
    "orphaned_references_removed": [
        { "footprint_name": "RESC0603", "removed_count": 2 }
    ],
    "total_removed": 2,
    "dry_run": false
}

`bulk_rename`

Rename multiple components in a library using pattern matching. Supports glob patterns and
regex with capture groups for flexible bulk renaming operations.

{
    "name": "bulk_rename",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "pattern": "^RESC(.*)$",
        "replacement": "RES_$1",
        "pattern_type": "regex",
        "dry_run": true
    }
}

Parameter	Description
`filepath`	Path to the library file (.PcbLib or .SchLib)
`pattern`	Pattern to match component names
`replacement`	Replacement string (use `$1`, `$2`, etc. for regex capture groups)
`pattern_type`	Pattern type: `glob` or `regex` (default: `glob`)
`dry_run`	If `true`, preview changes without modifying the file (default: `false`)

Example Response:

{
    "renamed": [
        { "old_name": "RESC0402", "new_name": "RES_0402" },
        { "old_name": "RESC0603", "new_name": "RES_0603" }
    ],
    "skipped": [],
    "conflicts": [],
    "dry_run": true
}

Pattern Examples:

Pattern Type	Pattern	Replacement	Input	Output
glob	`RESC*`	`RES_`	`RESC0603`	`RES_0603` (suffix preserved)
regex	`^RESC(.*)$`	`RES_$1`	`RESC0603`	`RES_0603`
regex	`^(.*)_V(\d+)$`	`$1_REV$2`	`CAP_V2`	`CAP_REV2`

`component_exists`

Check if one or more components exist in an Altium library. Useful for validating references
before performing operations like copy or merge.

{
    "name": "component_exists",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "component_names": ["RESC0603", "CAPC0402", "MISSING_COMPONENT"]
    }
}

Parameter	Required	Description
`filepath`	Yes	Path to the library file (.PcbLib or .SchLib)
`component_names`	Yes	Array of component names to check

Response:

{
    "status": "success",
    "filepath": "./MyLibrary.PcbLib",
    "file_type": "PcbLib",
    "results": [
        { "name": "RESC0603", "exists": true },
        { "name": "CAPC0402", "exists": true },
        { "name": "MISSING_COMPONENT", "exists": false }
    ],
    "all_exist": false,
    "found_count": 2,
    "missing_count": 1
}

`update_pad`

Update specific properties of a pad in a PcbLib footprint without replacing the entire component.
Find the pad by designator and update only the specified properties.

{
    "name": "update_pad",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "component_name": "RESC0603",
        "designator": "1",
        "updates": {
            "width": 1.0,
            "height": 0.9,
            "shape": "rectangle"
        },
        "dry_run": false
    }
}

Parameter	Required	Description
`filepath`	Yes	Path to the PcbLib file
`component_name`	Yes	Name of the footprint
`designator`	Yes	Pad designator to update (e.g., "1", "A1")
`updates`	Yes	Object with properties to update
`dry_run`	No	Preview changes without modifying the file (default: `false`)

Updatable Pad Properties:

Property	Description
`x`, `y`	Position in mm
`width`, `height`	Pad dimensions in mm
`shape`	Pad shape: `rectangle`, `round`, `oval`, `rounded_rectangle`
`rotation`	Rotation angle in degrees
`hole_size`	Hole diameter in mm (for through-hole pads)

Response:

{
    "status": "success",
    "component_name": "RESC0603",
    "designator": "1",
    "changes": [
        { "property": "width", "old": 0.9, "new": 1.0 },
        { "property": "height", "old": 0.95, "new": 0.9 },
        { "property": "shape", "old": "RoundedRectangle", "new": "rectangle" }
    ]
}

`update_primitive`

Update specific properties of a primitive (track, arc, text, fill, region) in a PcbLib footprint.
Find the primitive by type and index, and update only the specified properties.

{
    "name": "update_primitive",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "component_name": "RESC0603",
        "primitive_type": "track",
        "index": 0,
        "updates": {
            "width": 0.15,
            "layer": "Top Overlay"
        },
        "dry_run": false
    }
}

Parameter	Required	Description
`filepath`	Yes	Path to the PcbLib file
`component_name`	Yes	Name of the footprint
`primitive_type`	Yes	Type: `track`, `arc`, `text`, `fill`, `region`
`index`	Yes	Zero-based index of the primitive in its type array
`updates`	Yes	Object with properties to update
`dry_run`	No	Preview changes without modifying the file (default: `false`)

Updatable Properties by Type:

Type	Properties
`track`	`x1`, `y1`, `x2`, `y2`, `width`, `layer`
`arc`	`x`, `y`, `radius`, `start_angle`, `end_angle`, `width`, `layer`
`text`	`x`, `y`, `text`, `height`, `rotation`, `layer`
`fill`	`x1`, `y1`, `x2`, `y2`, `rotation`, `layer`
`region`	`layer`

`list_backups`

List available backup files for an Altium library. Backups are created automatically before
destructive operations.

{
    "name": "list_backups",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib"
    }
}

Parameter	Required	Description
`filepath`	Yes	Path to the library file

Response:

{
    "status": "success",
    "filepath": "./MyLibrary.PcbLib",
    "backups": [
        {
            "filename": "MyLibrary.PcbLib.20260126_143022.bak",
            "path": "./MyLibrary.PcbLib.20260126_143022.bak",
            "timestamp": "2026-01-26T14:30:22",
            "size_bytes": 45678
        },
        {
            "filename": "MyLibrary.PcbLib.20260125_091500.bak",
            "path": "./MyLibrary.PcbLib.20260125_091500.bak",
            "timestamp": "2026-01-25T09:15:00",
            "size_bytes": 44123
        }
    ],
    "backup_count": 2
}

`restore_backup`

Restore an Altium library from a backup file. If no specific backup is specified, restores
from the most recent backup.

{
    "name": "restore_backup",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "backup_filename": "MyLibrary.PcbLib.20260125_091500.bak"
    }
}

Parameter	Required	Description
`filepath`	Yes	Path to the library file to restore
`backup_filename`	No	Specific backup filename to restore (default: most recent)

Response:

{
    "status": "success",
    "filepath": "./MyLibrary.PcbLib",
    "restored_from": "MyLibrary.PcbLib.20260125_091500.bak",
    "backup_timestamp": "2026-01-25T09:15:00",
    "message": "Restored './MyLibrary.PcbLib' from backup 'MyLibrary.PcbLib.20260125_091500.bak'"
}

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	Value	Usage
Rectangle	`"rectangle"`	Pin 1 indicator — use for the first pad to distinguish it visually
Rounded Rectangle	`"rounded_rectangle"`	Default for SMD pads (most common)
Round	`"round"` or `"circle"`	Circular pads, default for through-hole (both values are equivalent)
Oval	`"oval"`	Oblong pads for constrained spaces

Example — marking pin 1 with a rectangular pad:

{
    "pads": [
        { "designator": "1", "x": -0.75, "y": 0, "width": 0.9, "height": 0.95, "shape": "rectangle" },
        { "designator": "2", "x": 0.75, "y": 0, "width": 0.9, "height": 0.95, "shape": "rounded_rectangle" }
    ]
}

This follows the IPC-7351 convention where pin 1 has a distinct shape (typically rectangular or square corners) while other pads use rounded corners.

Symbol Primitives (SchLib)

Primitive	Description
Pin	Component pin with name, designator, electrical type, orientation
Rectangle	Filled or unfilled rectangle (component body)
RoundRect	Rounded rectangle with corner radii
Line	Single line segment
Polyline	Multiple connected line segments
Polygon	Filled polygon with border and fill colours
Arc	Arc or circle
Ellipse	Ellipse or circle (filled or unfilled)
EllipticalArc	Elliptical arc segment with fractional radii
Bezier	Cubic Bezier curve (4 control points)
Label	Text label (RECORD=4)
Text	Text annotation (RECORD=3)
Parameter	Component parameter (Value, Part Number, etc.)
FootprintModel	Reference to a footprint in a PcbLib

Standard Altium Layers

Common layers for footprints (each has a Bottom equivalent):

Layer	Usage
Top Layer	Copper pads (SMD)
Bottom Layer	Bottom copper pads
Multi-Layer	Through-hole pads (all copper layers)
Top Overlay	Silkscreen
Top Paste	Solder paste stencil
Top Solder	Solder mask openings
Top Assembly	Assembly outline (documentation)
Top Courtyard	Courtyard boundary (IPC-7351)
Top 3D Body	3D model outline

Additional layers supported:

Layer	Usage
Mid-Layer 1–30	Internal copper layers
Internal Plane 1–16	Power/ground planes
Mechanical 1–16	User-defined mechanical layers
Drill Guide	Drill hole markers
Drill Drawing	Drill chart/table
Keep-Out Layer	Routing exclusion zones

Installation

See CONTRIBUTING.md § Development Setup for build instructions.

The release binary will be at target/release/altium-designer-mcp.

Command-Line Usage

altium-designer-mcp [OPTIONS] [CONFIG_FILE]

Option	Description
`CONFIG_FILE`	Path to configuration file (optional, uses default location if omitted)
`-v`, `--verbose`	Increase logging verbosity (`-v` info, `-vv` debug, `-vvv` trace)
`-q`, `--quiet`	Decrease logging verbosity (only show errors)
`-h`, `--help`	Print help information
`-V`, `--version`	Print version information

Usage with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
    "mcpServers": {
        "altium": {
            "command": "altium-designer-mcp",
            "args": ["/path/to/config.json"]
        }
    }
}

Configuration

Configuration file location:

Linux/macOS: ~/.altium-designer-mcp/config.json
Windows: %USERPROFILE%\.altium-designer-mcp\config.json

{
    "allowed_paths": [
        "/path/to/your/altium/libraries",
        "/another/library/path"
    ],
    "logging": {
        "level": "warn"
    }
}

Configuration Options

Option	Description
`allowed_paths`	Array of directory paths where library files can be accessed (default: current directory)
`logging.level`	Log level: trace, debug, info, warn, error (default: warn)

STEP Model Integration

STEP models are attached, not generated. The tool links existing STEP files to footprints.

{
    "step_model": {
        "filepath": "./3d-models/0603.step",
        "x_offset": 0,
        "y_offset": 0,
        "z_offset": 0,
        "rotation": 0
    }
}

Embedded vs External Models

Altium supports two ways to reference 3D models:

Type	Storage	Portability
Embedded	STEP data stored inside the .PcbLib file	Fully portable — the model travels with the library
External	File path reference to a .step file on disk	Not portable — requires the file to exist at the referenced path

When using copy_component_cross_library or merge_libraries:

Embedded models are copied along with the component
External model references are removed with a warning, as the file paths are not portable across different machines or directory structures

To preserve 3D models when copying components, ensure they are embedded in the source library (not external references).

Extracting Embedded Models

Use extract_step_model to extract embedded STEP data from a library:

{
    "name": "extract_step_model",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "output_path": "./extracted_model.step"
    }
}

For parametric 3D model generation, a dedicated mechanical MCP server is planned as a future project.

Automatic Backups

Before any destructive operation (delete, update, merge, batch update), the server automatically
creates a timestamped backup of the target file. Backups use the format:

MyLibrary.PcbLib.20260125_143022.bak

Backup retention: Only the 5 most recent backups per file are kept. Older backups are
automatically removed to prevent unbounded disk usage.

Operations that create backups:

delete_component
update_component
update_pad
update_primitive
rename_component
copy_component
copy_component_cross_library (target file)
merge_libraries (target file)
reorder_components
batch_update
bulk_rename
write_pcblib / write_schlib (when overwriting)
import_library (when overwriting)

Disabling backups: All write operations accept a create_backup parameter (default: true).
Set to false to skip backup creation:

{
    "name": "delete_component",
    "arguments": {
        "filepath": "./MyLibrary.PcbLib",
        "component_names": ["OLD_COMPONENT"],
        "create_backup": false
    }
}

Managing backups: Use list_backups to view available backups and restore_backup to
recover from a previous version.

Dry-run support: Most destructive operations support dry_run=true to preview changes
without modifying files:

delete_component — preview which components would be deleted
update_component — preview component replacement changes
update_pad / update_primitive — preview property changes
bulk_rename — preview name changes
repair_library — preview orphaned references to remove
copy_component / rename_component / reorder_components
write_pcblib / write_schlib / import_library
copy_component_cross_library / merge_libraries

Notes

Long Component Names

Component names longer than 31 characters are supported. The OLE Compound File format limits
storage names to 31 characters, so longer names are automatically truncated internally while
the full name is preserved in component parameters. This is handled transparently — you can
use any length component name and it will be preserved on read/write roundtrips.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Follow the style guide in STYLE.md
Security issues: see SECURITY.md

Development

Running Tests

cargo test

Tests are self-contained and generate their own data programmatically. Temporary files are created in .tmp/ (git-ignored) and automatically cleaned up.

Code Quality

cargo fmt --check  # Check formatting
cargo clippy       # Lint

Licence

GNU General Public License v3.0 — see LICENCE.

Sample Files

Sample Altium library files are included in the scripts/ folder for manual debugging only.
Automated tests do not depend on these files.

See scripts/README.md for details on available sample files and analysis scripts.

Prior Art

This project builds on the work of:

AltiumSharp — C# Altium file parser (MIT)
pyAltiumLib — Python Altium library
python-altium — Altium format documentation

altium-designer-mcp

The Core Idea

Quick Start with Claude Code

How It Works

MCP Tools

read_pcblib

write_pcblib

read_schlib

write_schlib

list_components

extract_style

delete_component

validate_library

export_library

extract_step_model

import_library

diff_libraries

batch_update

copy_component

rename_component

copy_component_cross_library

merge_libraries

reorder_components

update_component

search_components

get_component

compare_components

render_footprint

render_symbol

manage_schlib_parameters

manage_schlib_footprints

repair_library

bulk_rename

component_exists

update_pad

update_primitive

list_backups

restore_backup

Primitive Types

Footprint Primitives (PcbLib)

Pad Shapes and Pin 1 Indicator

Symbol Primitives (SchLib)

Standard Altium Layers

Installation

Command-Line Usage

Usage with Claude Desktop

Configuration

Configuration Options

STEP Model Integration

Embedded vs External Models

Extracting Embedded Models

Automatic Backups

Notes

Long Component Names

Contributing

Development

Running Tests

Code Quality

Licence

Links

Sample Files

Prior Art

Yorumlar (0)

`read_pcblib`

`write_pcblib`

`read_schlib`

`write_schlib`

`list_components`

`extract_style`

`delete_component`

`validate_library`

`export_library`

`extract_step_model`

`import_library`

`diff_libraries`

`batch_update`

`copy_component`

`rename_component`

`copy_component_cross_library`

`merge_libraries`

`reorder_components`

`update_component`

`search_components`

`get_component`

`compare_components`

`render_footprint`

`render_symbol`

`manage_schlib_parameters`

`manage_schlib_footprints`

`repair_library`

`bulk_rename`

`component_exists`

`update_pad`

`update_primitive`

`list_backups`

`restore_backup`