altium-designer-mcp

altium-designer-mcp

让 AI 构建你的 Altium 库——由它负责工程设计，这个工具负责写入文件。

一个 MCP 服务，为 AI 助手（Claude Code、Claude Desktop、Cursor、Antigravity、VS Code Copilot——任何 MCP 客户端）提供文件 I/O 和图元放置工具，用于处理 Altium Designer .PcbLib（封装）和 .SchLib（符号） 库——让 AI 能够创建和维护任何元件，而不只是预先编程好的封装。

---

问题所在

手动构建 Altium 元件库既缓慢又重复——每个封装都意味着要查找 IPC-7351B 焊盘尺寸、禁布区和丝印层信息，然后 手动放置每个图元。AI 助手擅长的正是这类推理，但它们无法写入 Altium 的 二进制 .PcbLib/.SchLib 文件——这是一种未公开文档的 OLE 复合格式，很容易 损坏，而且 Altium 遇到格式错误的文件时会静默拒绝打开。

方案	问题
在 Altium 中手动绘制每个封装	缓慢且重复；AI 无法操作文件
让 AI 直接输出二进制文件	生成的文件会损坏，Altium 无法打开
预编程的封装生成器	只能生成有人预先编写代码支持的封装类型

---

核心理念

AI 负责智能处理，工具负责文件 I/O。

职责	负责方
IPC-7351B 计算	AI
封装布局决策	AI
样式选择	AI
数据手册解读	AI
读取/写入 Altium 文件	本工具
图元放置	本工具
STEP 模型附加	本工具

这意味着 AI 可以创建任何封装——而不仅是预先编程好的封装类型。 完整的架构设计依据请参阅 docs/VISION.md。

---

适用人群

任何构建或维护 Altium 元件库，并使用支持 MCP 的 AI 助手的人。AI 负责工程设计（数据手册 → 尺寸 → 样式）；此服务让 AI 能够 读取和写入实际的 .PcbLib / .SchLib 文件。

如果你……	那么……
使用 Claude Code、Claude Desktop、Cursor、Antigravity、VS Code + Copilot——任何 MCP 客户端——并在 Altium 中进行设计	✅ 适合你
想要针对固定封装集合的预制生成器	❌ 不适合——本项目的目标是支持任何元件
不使用 Altium	❌ 不适用

---

快速开始

客户端配置——适用于 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 及其他任何 stdio MCP 客户端的已验证配置，并提供故障排除指南——支持 Windows、Linux 和 macOS。

使用此服务——连接后可以提出哪些请求：示例 工作流、提示词和技巧，所有客户端均相同。

---

工作原理

┌─────────────────────────────────────────────────────────────────────────────┐
│  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 工具

该服务提供 34 个工具，可处理 .PcbLib（封装）和 .SchLib（符号）。每个工具的完整参数和示例见 docs/TOOLS.md——此处提供分类概览。

读取与写入

工具	用途
read_pcblib	从 .PcbLib 读取封装。
write_pcblib	将封装写入 .PcbLib。
read_schlib	从 .SchLib 读取符号。
write_schlib	将符号写入 .SchLib。

检查与可视化

工具	用途
list_components	列出元件名称（分页）。
get_component	获取单个元件的完整数据。
search_components	使用正则表达式/通配符搜索各个库。
component_exists	检查元件是否存在。
render_footprint	以 ASCII 艺术预览封装。
render_symbol	以 ASCII 艺术预览符号。
extract_style	从现有库中提取样式。

比较

工具	用途
diff_libraries	比较两个库文件。
compare_components	对比两个指定元件。

就地编辑

工具	用途
update_component	更新元件，同时保留其位置。
update_pad	更新单个焊盘的属性。
update_primitive	更新单个图元（走线/圆弧/文本/填充/区域）。
batch_update	批量更新所有元件。
reorder_components	重新排列库中的元件。
manage_schlib_parameters	列出/获取/设置/移除 SchLib 参数。
manage_schlib_footprints	管理 SchLib 符号中的封装链接。

管理元件

工具	用途
delete_component	删除一个或多个元件。
copy_component	在库中复制元件。
rename_component	重命名元件（原子操作）。
copy_component_cross_library	将元件复制到另一个库。
bulk_rename	根据模式批量重命名。

库操作

工具	用途
merge_libraries	将多个库合并为一个。
write_libpkg	写入 .LibPkg 项目，将多个库组合起来以编译 IntLib。
export_library	导出为 JSON/CSV。
import_library	从 JSON 导入（与导出相反）。
validate_library	检查常见问题。
repair_library	移除孤立数据。
extract_step_model	提取嵌入的 STEP 3D 模型。

备份与安全

工具	用途
list_backups	列出自动备份。
restore_backup	从备份恢复。

图元类型

封装图元（PcbLib）

图元	描述
Pad	表面贴装或通孔焊盘，具有位号、位置、尺寸、形状、层（参见下方的焊盘形状）、电源平面热焊盘，以及独立的多边形连接样式
Via	垂直互连，具有层跨度、孔径和热焊盘
Track	任意层上的线段（丝印、装配层等）
Arc	任意层上的弧线或圆
Region	填充的多边形（器件边界、覆铜区域），可带有孔洞轮廓
Text	具有字体、字号、位置和所在层的文本字符串
Fill	任意层上的填充矩形
ComponentBody	3D 模型引用（嵌入式 STEP 模型）

焊盘形状和 1 脚标识

焊盘的 shape 属性用于控制铜箔形状。可用它来标识 1 脚：

形状	值	用法
矩形	"rectangle"	1 脚标识——将第一个焊盘设为矩形，以便在视觉上区分
圆角矩形	"rounded_rectangle"	表面贴装焊盘的默认形状（最常见）
圆形	"round" 或 "circle"	圆形焊盘，通孔焊盘的默认形状（这两个值等效）
椭圆	"oval"	适用于受限空间的长圆形焊盘
八边形	"octagonal"	八边形焊盘（倒角）

示例——使用矩形焊盘标记 1 脚：

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

这遵循 IPC-7351 规范：1 脚采用独特的形状（通常为矩形或带直角），而其他焊盘采用圆角。

符号图元（SchLib）

图元	描述
Pin	元件引脚，具有名称、位号、电气类型和方向
Rectangle	填充或未填充的矩形（元件主体）
RoundRect	带圆角半径的圆角矩形
Line	单条线段
Polyline	多条相连的线段
Polygon	带边框和填充颜色的填充多边形
Arc	弧线或圆
Pie	填充的圆形扇区（弧线几何图形加填充）
Image	带边界框的嵌入式或链接的光栅图像
Ellipse	椭圆或圆（填充或未填充）
EllipticalArc	具有分数半径的椭圆弧段
Bezier	三次贝塞尔曲线（4 个控制点）
Label	文本字符串（RECORD=4）——符号中唯一的自由文本
IeeeSymbol	IEEE 符号字形（RECORD=3）：点、时钟、低电平有效输入等
TextFrame	带边框的多行文本框（自动换行、对齐）
Parameter	元件参数（Value、Part Number 等）
FootprintModel	对 PcbLib 中封装的引用

Altium 标准层

封装常用层（每层都有对应的底层）：

层	用法
Top Layer	铜焊盘（表面贴装）
Bottom Layer	底层铜焊盘
Multi-Layer	通孔焊盘（所有铜层）
Top Overlay	丝印
Top Paste	焊膏模板
Top Solder	阻焊开窗
Top Assembly	装配轮廓（文档用途）
Top Courtyard	器件边界（IPC-7351）
Top 3D Body	3D 模型轮廓

支持的其他层：

层	用法
Mid-Layer 1–30	内部铜层
Internal Plane 1–16	电源/接地平面
Mechanical 1–32	用户定义的机械层
Drill Guide	钻孔标记
Drill Drawing	钻孔图表
Keep-Out Layer	布线禁布区

层名称可以使用 Altium 的拼写形式（Top Overlay、Mechanical 13），也可以使用驼峰形式（TopOverlay、Mechanical13），大小写均可；所有工具都接受相同的写法。

---

安装

预编译二进制文件适用于 Linux（x86_64）、macOS（aarch64）和 Windows（x86_64），可从 Releases 页面获取——每个 压缩包都附带安装 README 和 docs/CLIENT_SETUP.md，其中介绍了如何将服务接入我们所知的所有 MCP 客户端。Linux 二进制文件需要 glibc 2.34 或更高版本： Ubuntu 22.04、Debian 12、RHEL 9（以及 AlmaLinux 和 Rocky Linux 9 等免费重构版）及更高版本。

Claude Desktop 用户无需下载压缩包：在同一页面获取一键安装扩展 altium-designer-mcp.mcpb（较旧版本：相同的 altium-designer-mcp.dxt），然后依次选择 Settings → Extensions → Advanced settings → Install Extension… — 参见 CLIENT_SETUP.md § Claude Desktop。

代码签名政策：docs/CODE_SIGNING_POLICY.md。Windows 二进制文件计划通过 SignPath Foundation 签名；在获批之前，这些文件不会签名，且每个版本都会附带签名的构建来源证明。

在容器中运行——适用于 Linux 主机、NAS 或 CI 作业，可将库生成到挂载文件夹中（无需在容器内安装 Altium）：仓库中的 Dockerfile 会生成与已发布二进制文件相同的 --locked 发布构建。

docker build -t altium-designer-mcp .
docker run -i --rm -v /path/to/libraries:/libraries altium-designer-mcp

挂载的 /libraries 文件夹就是容器的完整允许列表。在客户端配置中，设置 "command": "docker" 和 "args": ["run", "-i", "--rm", "-v", "/path/to/libraries:/libraries", "altium-designer-mcp"]。

如需改为从源代码构建，请参见 CONTRIBUTING.md § Development Setup；优化后的 二进制文件由 cargo build --release 生成，位于 target/release/altium-designer-mcp。

验证下载的版本

发布的压缩包由 GitHub Actions 构建，并附有已签名的 SLSA 构建来源证明，因此可以追溯下载文件对应的工作流运行和提交：

gh attestation verify <archive> --repo embedded-society/altium-designer-mcp
sha256sum --check --ignore-missing SHA256SUMS.txt

这些二进制文件未经代码签名，因此 Windows SmartScreen 和 macOS Gatekeeper 会在首次运行时发出警告（在 macOS 上，右键单击 → Open）。来源证明是更可靠的验证方式。 有关版本的生成方式，请参见 docs/RELEASING.md。

命令行用法

altium-designer-mcp [OPTIONS] [CONFIG_FILE]

选项	说明
CONFIG_FILE	配置文件的路径（可选；省略时使用默认位置）
--allow <DIR>...	直接授予对库文件夹的访问权限（可重复指定）。添加到配置文件的 allowed_paths 中；即使没有配置文件也能使用——此时其他设置将采用默认值
--ansi-code-page <PAGE>	写入新封装名称时使用的 Windows ANSI 代码页；检测到库的代码页时优先尝试该值，库未指定代码页时也使用该值（936 表示 GBK，1250、1252 等）；覆盖配置文件中的 ansi_code_page
--http <ADDR>	在此地址（例如 127.0.0.1:8080）的 /mcp 路径上提供 MCP Streamable HTTP 传输，而不是 stdio。除非在 ALTIUM_DESIGNER_MCP_HTTP_TOKEN 中设置了 bearer token，否则不允许使用非回环地址。参见 docs/CLIENT_SETUP.md § HTTP transport
--http-allow-origin <ORIGIN>...	允许访问 HTTP 传输的浏览器源，除本地源外还可重复指定
-v、--verbose	提高日志详细程度（-v 为 info，-vv 为 debug，-vvv 为 trace）
-q、--quiet	降低日志详细程度（仅显示错误）
-h、--help	打印帮助信息
-V、--version	打印版本信息

连接 AI 客户端

每个 MCP 客户端都需要相同的两个绝对路径——二进制文件和配置文件——区别仅在于它们写入的位置。大多数客户端读取的标准配置块：

{
    "mcpServers": {
        "altium": {
            "command": "/usr/local/bin/altium-designer-mcp",
            "args": ["/home/you/.altium-designer-mcp/config.json"]
        }
    }
}

Claude Desktop、Cursor、VS Code、Windsurf、Cline、Zed、JetBrains、Gemini CLI、Codex CLI 等客户端的配置位置，以及客户端无法看到服务时的处理方法，请参阅 docs/CLIENT_SETUP.md。请使用绝对路径：客户端不会为你搜索 PATH 或展开 ~。

---

配置

服务读取一个 JSON 文件，也可以不读取：altium-designer-mcp --allow <DIR> 会在命令行中授权文件夹，其余配置使用默认值；Claude Desktop 扩展就是这样启动服务的。配置文件位置：

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

配置选项

选项	描述
allowed_paths	可访问库文件的目录路径数组；--allow 会向其中添加路径（若两者均未授权任何路径，默认值为当前工作目录）
logging.level	日志级别：trace、debug、info、warn、error（默认值：warn）
logging.audit_log_path	破坏性操作的仅追加 JSON 行审计日志路径（默认值：null——不写入审计日志）
rate_limit.max_burst	限流前可执行的变更操作最大突发数量；只读工具永不受速率限制（默认值：120）
rate_limit.refill_per_sec	变更操作的令牌桶补充速率，单位为每秒令牌数（默认值：30.0）
ansi_code_page	写入新封装名称时使用的 Windows ANSI 代码页：874、932、936、949、950、1250 至 1258 或 65001。检测库的代码页时，读取器也会优先尝试此代码页；对于未显示代码页的库，也会使用此代码页读取。Altium Designer 21 会通过计算机的代码页，从这些字节中显示封装名称，因此此处应设为打开这些库的 Altium 所在计算机的代码页（默认值：null——Windows 上为系统代码页，其他平台为 1252）

---

STEP 模型集成

STEP 模型是附加的，而非生成的。该工具会将现有 STEP 文件关联到封装。

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

嵌入式与外部模型

Altium 支持两种 3D 模型引用方式：

类型	存储方式	可移植性
嵌入式	STEP 数据存储在 .PcbLib 文件中	完全可移植——模型随库一起移动
外部	指向磁盘上 .step 文件的文件路径引用	不可移植——引用路径下必须存在该文件

在库之间复制或合并元件时：

• 嵌入式模型会随元件一起移动——copy_component_cross_library 和 merge_libraries 都会将引用的模型数据流复制到目标库（多个封装共用的模型只复制一次），因此移动后模型仍可正常解析。
• 外部模型引用：默认情况下，copy_component_cross_library 会移除这些引用并发出警告，因为相对于源库的路径通常无法在其他位置解析——传入 preserve_external_paths=true 可保留这些引用。merge_libraries 会原样保留它们。

在源库中嵌入模型，是确保 3D 数据在任何复制操作中都能保留的可靠方式。

提取嵌入式模型

使用 extract_step_model 从库中提取嵌入式 STEP 数据：

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

用于参数化 3D 模型生成的专用机械 MCP 服务计划作为未来项目开发。

---

自动备份

在执行任何破坏性操作（删除、更新、合并、批量更新）之前，服务会自动 为目标文件创建带时间戳的备份。备份格式如下：

MyLibrary.PcbLib.20260125_143022.bak

备份不会覆盖其他备份：如果在同一秒内创建第二个备份，文件名会是 MyLibrary.PcbLib.20260125_143022_001.bak，然后依次为 _002，等等。

备份保留策略： 每个文件保留最近的 5 个备份，以及服务启动后为该文件创建的第一个备份，该备份保存文件在本次会话更改之前的状态。较旧的备份会自动删除，以防磁盘使用量不受限制地增长。

会创建备份的操作：

• delete_component
• update_component
• update_pad
• update_primitive
• rename_component
• copy_component
• copy_component_cross_library（目标文件）
• merge_libraries（目标文件）
• reorder_components
• batch_update
• bulk_rename
• repair_library
• manage_schlib_parameters
• manage_schlib_footprints
• write_pcblib / write_schlib（覆盖时）
• import_library（覆盖时）
• restore_backup（所选备份替换当前文件之前）

管理备份： 使用 list_backups 查看可用备份，使用 restore_backup 恢复到以前的版本。

支持试运行： 以下操作支持 dry_run=true，可预览更改而不修改文件：

• delete_component — 预览将删除哪些元件
• update_component — 预览元件替换更改
• update_pad / update_primitive — 预览属性更改
• bulk_rename — 预览名称更改
• repair_library — 预览将移除的孤立引用
• batch_update — 预览整个库范围的更新
• copy_component / rename_component / merge_libraries

---

说明

来自非西方语言 Windows 的库

Altium 会将大多数名称存储为纯字节，使用写入这些名称的计算机的 Windows 代码页，且不记录所用的代码页。因此，在中文、日文、韩文、中欧、西里尔文、希腊文、土耳其文、波罗的海语、希伯来文、阿拉伯文、越南文或泰文 Windows 上创建的库，在假定使用 Windows-1252 的工具中读取时会出现乱码（例如，（0402 显示为 £¨0402）。

本服务会根据焊盘封装推断库的代码页；这些焊盘封装的真实名称会记录两次，一次是字节形式，一次是 Unicode 形式。服务会通过该代码页读取所有名称，并原样写回，因此重写后的字节保持完全一致。读取或编辑这类库无需进行任何配置。

有两种情况需要注意：

• Altium 必须显示的名称。 Altium Designer 21 及更早版本会从字节中读取焊盘封装名称，并通过运行它们的计算机所用的代码页进行解码，而且从不读取 Unicode 副本。因此，新建或重命名的焊盘封装会以服务自身的代码页写入——在 Windows 上即系统代码页。如果服务运行的计算机与打开这些库的 Altium 所用区域设置不同，请在配置文件中使用 ansi_code_page，或在命令行中使用 --ansi-code-page 指定该代码页（874、932、936、949、950、1250 至 1258，或 65001）。
• 代码页无法表示的字符。 Altium 会用 ? 替代该字符，本服务也一样；完整名称仍会像 Altium 保留名称那样保存在元件参数中，并会在下次读取时完整恢复。

较长的元件名称

支持超过 31 个字符的元件名称。OLE 复合文件格式将存储名称限制为 31 个字符，因此较长的名称会在内部自动截断，而完整名称会保存在元件参数中。此过程会透明处理——元件名称长度不限，读写往返后都能完整保留。

---

隐私政策

altium-designer-mcp 是一个本地工具，不会收集任何信息。

• 数据收集：无。服务端没有遥测或分析功能，也不会联系任何服务，包括本项目的服务。使用 --http 时，它会在你指定的地址监听 MCP 客户端；仍不会向任何地方发送数据。
• 使用与存储：它只会读取和写入你授权的文件夹（allowed_paths 或 --allow）中的库文件，以及在修改前于文件旁创建的带时间戳 .bak 备份。可选的审计日志（logging.audit_log_path）是你指定的本地文件，其中记录工具名称、文件名和操作结果，不包含库文件内容。
• 第三方共享：无。任何内容都不会离开你的设备。
• 数据保留：文件和备份会一直保留，直到你将其删除；每个库最多保留最近的 5 个备份。
• 联系：发送邮件至 [email protected]，或在 GitHub issue 中反馈无需保密的问题。

---

文档

适用场景	阅读内容
将服务端接入 AI 客户端	docs/CLIENT_SETUP.md — 每个客户端各有一个章节
连接后可以提出什么请求	docs/USAGE.md — 工作流、提示词和技巧
指导 AI 如何有效使用它	docs/AGENT_GUIDE.md（粘贴到项目简介中）、docs/AI_WORKFLOW.md
每个工具、参数和示例	docs/TOOLS.md；错误消息见 docs/errors.md
了解如此设计的原因	docs/VISION.md、docs/ARCHITECTURE.md
逐字节了解文件格式	docs/PCBLIB_FORMAT.md、docs/SCHLIB_FORMAT.md
安全模型和威胁分析	docs/SECURITY.md（报告问题：SECURITY.md）
了解如何构建和验证发行版本	docs/RELEASING.md；代码签名政策

---

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

• 遵循 STYLE.md 中的风格指南
• 安全问题：请参阅 SECURITY.md

---

开发

cargo test

写入路径测试会以编程方式生成所需数据；读取器测试会解析已提交的 Altium 编写黄金测试样例（见示例文件）。临时文件会创建在 .tmp/（已加入 git 忽略规则）中，并在完成后自动清理。

完整的构建、格式化和 lint 命令以 CONTRIBUTING.md § 开发环境设置 中的内容为准。

---

许可

版权所有 (C) 2026 The Embedded Society https://github.com/embedded-society/altium-designer-mcp。

GNU General Public License v3.0 — 详见 LICENCE。

---

链接

• MCP 规范
• 报告问题

---

示例文件

Altium 编写的示例库已作为黄金测试样例提交至 scripts/samples/：读取器测试（tests/samples_pcblib.rs、tests/samples_schlib.rs）会在 CI 中将其解析为基准事实。用于（重新）生成这些文件的 PowerShell/DelphiScript 工具需要真实的 Altium 安装，且仅供手动使用。

有关示例文件和现场工具的详情，请参阅 scripts/README.md。

---

先行项目与致谢

本项目建立在多个优秀开源项目的基础之上，我们对它们一一表示感谢：

• AltiumSharp (MIT) — 最完善的开源 Altium 读取器/写入器。我们将其作为权威参考（其 DTO、二进制序列化代码和黄金版 TestData），以便根据真实数据验证我们的二进制格式。
• pyAltiumLib — 一个独立的 Python 读取器，在 CI 中作为我们的可读性验证器（tests/integration/），用于检查生成的文件是否确实能够解析。
• python-altium — 早期的 Altium 格式文档。
• coffeenmusic/altium-mcp (MIT) — 一个驱动实时 Altium 应用的 MCP 服务。它与本项目互为补充（我们在离线状态下生成和编辑库文件；它则控制正在运行的会话）。我们借鉴了它的 RunScript 启动方式和基于文件的桥接模式，用于我们的现场 Altium 自动化（scripts/altium/）。