Altium MCP工具

Installation

See CONTRIBUTING.md § Development Setup for build instructions.

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

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.

---

Command-Line Usage

altium-designer-mcp [OPTIONS] [CONFIG_FILE]

Usage with Claude Desktop

Add to your Claude Desktop MCP configuration:

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

---

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.

---

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

---

`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
    }
}

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 }
    ]
}

`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
    }
}

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

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

`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"
    }
}

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"
    }
}

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
    }
}

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

`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"]
    }
}

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"}
            ]
        }
    }
}

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"
    }
}

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"
    }
}

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"
    }]
}

`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"]
    }
}

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
}

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
    }
}

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.

---

`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
    }
}

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 }
        ]
    }
}

Embedded vs External Models

Altium supports two ways to reference 3D models:

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).