Codex 接入 Ant Design MCP Server：让 AI 写 AntD 代码不再靠猜

__Mustang?

439人浏览 · 2026-05-05 17:28:29

__Mustang? · 2026-05-05 17:28:29 发布

Ant Design MCP Server 在 OpenAI Codex 中的安装与配置详细教程

本文写于 2026-05-05。Ant Design 官方已在 @ant-design/cli v6.3.5 起提供 MCP Server，可通过 antd mcp 启动；@ant-design/cli 当前 npm 最新版为 6.3.7，要求 Node.js >=20.0.0。

一、为什么要在 Codex 中安装 Ant Design MCP Server

使用 Codex 写 React + Ant Design 项目时，模型很容易遇到这些问题：

组件 API 记忆不准，尤其是不同版本之间的差异；
写出来的示例和当前 Ant Design 文档不一致；
设计 Token、语义化 DOM、组件示例需要反复查文档；
迁移或排查问题时，需要快速查看 changelog。

MCP，全称 Model Context Protocol，是一种让 AI 工具连接外部能力的协议。安装 Ant Design MCP Server 后，Codex 可以直接查询 Ant Design 的组件列表、组件 API、完整文档、可运行示例、Design Token、语义结构以及版本变更。

Ant Design 官方 MCP Server 目前提供的工具包括：

工具	作用
`antd_list`	列出可用组件
`antd_info`	获取组件属性规格
`antd_doc`	获取组件完整文档
`antd_demo`	获取可运行代码示例
`antd_token`	查询 Design Token
`antd_semantic`	查看 DOM 结构和样式钩子
`antd_changelog`	分析跨版本 API 变更

二、准备环境

安装前先确认本机具备以下环境：

Node.js >=20.0.0
npm
OpenAI Codex CLI 或 Codex Desktop App
能访问 npm registry

在终端检查版本：

node -v
npm -v
codex --version

如果你在 Windows PowerShell 中遇到 npm.ps1 被系统策略禁止加载，可以先改用：

npm.cmd -v

后续所有 npm 命令也可以替换成 npm.cmd。

三、安装 Ant Design CLI

Ant Design 官方 MCP Server 跟随 @ant-design/cli 提供，因此先全局安装 CLI：

npm install -g @ant-design/cli

Windows PowerShell 如果遇到脚本策略问题，使用：

npm.cmd install -g @ant-design/cli

安装完成后检查 antd 命令：

antd --version

如果 Windows 中提示找不到 antd，可以尝试：

antd.cmd --version

如果 antd.cmd 可以执行，后面 Codex 配置中的 command 建议写成 antd.cmd。

四、方式一：使用 Codex CLI 添加 MCP Server

这是最省事的方式。Codex 官方支持用 codex mcp add 管理 MCP Server。

macOS / Linux：

codex mcp add antd -- antd mcp

Windows 如果 antd 无法被 Codex 直接识别：

codex mcp add antd -- antd.cmd mcp

添加完成后查看 MCP Server 列表：

codex mcp list

如果列表中能看到 antd，说明配置已经写入 Codex。

五、方式二：手动修改 Codex 配置文件

Codex 当前官方配置文件是 TOML 格式，路径通常是：

macOS / Linux：~/.codex/config.toml
Windows：C:\Users\<你的用户名>\.codex\config.toml

注意：很多 MCP 客户端使用 mcpServers 的 JSON 配置，但 Codex 当前推荐使用 config.toml 中的 [mcp_servers] 配置。不要直接把其他工具的 JSON 配置粘进 Codex 的 TOML 文件。

macOS / Linux 示例：

[mcp_servers.antd]
command = "antd"
args = ["mcp"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 60

Windows 示例：

[mcp_servers.antd]
command = "antd.cmd"
args = ["mcp"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 60

如果你不想全局安装 @ant-design/cli，也可以使用 npx 方式：

[mcp_servers.antd]
command = "npx"
args = ["-y", "@ant-design/cli", "mcp"]
enabled = true
startup_timeout_sec = 60
tool_timeout_sec = 60

Windows 上如果 npx 启动失败，可以改成：

[mcp_servers.antd]
command = "npx.cmd"
args = ["-y", "@ant-design/cli", "mcp"]
enabled = true
startup_timeout_sec = 60
tool_timeout_sec = 60

六、固定 Ant Design 文档版本

如果你的项目还在使用 Ant Design 5.x，可以让 MCP Server 按指定版本返回文档。

例如固定为 5.20.0：

[mcp_servers.antd]
command = "antd"
args = ["mcp", "--version", "5.20.0"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 60

Windows 中仍然可以把 command 改成 antd.cmd。

七、重启 Codex 并验证

修改配置后，建议完整重启 Codex：

如果使用 Codex CLI，退出当前会话后重新执行 codex；
如果使用 Codex Desktop App，关闭当前 workspace 或重启应用；
如果在 Codex TUI 中，可以输入 /mcp 查看当前启用的 MCP Server。

也可以执行：

codex mcp list

然后在 Codex 中输入下面的测试提示词：

请使用 Ant Design MCP 查询 Button 组件的 API，并给一个 React 示例。

或者：

请列出 Ant Design MCP 当前可查询的组件，并查询 Table 组件的 pagination 用法。

如果 Codex 能调用 Ant Design MCP 并返回组件文档、API 或示例代码，说明安装成功。

八、常见问题排查

1. `npm.ps1` 无法加载

Windows PowerShell 可能会提示：

无法加载文件 npm.ps1，因为在此系统上禁止运行脚本

临时解决方式是使用：

npm.cmd install -g @ant-design/cli

如果希望长期解决，可以在 PowerShell 中执行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

执行前请确认你了解公司或个人电脑的脚本执行策略要求。

2. `antd` 命令找不到

先检查全局 npm bin 是否在 PATH 中：

npm prefix -g

Windows 可以尝试：

npm.cmd prefix -g
antd.cmd --version

如果 antd.cmd 可用，就在 Codex 配置里使用：

command = "antd.cmd"

3. Codex 没有识别 MCP Server

重点检查三件事：

配置文件路径是否正确：~/.codex/config.toml
TOML 语法是否正确，不要写成 JSON；
修改后是否已经重启 Codex。

也可以用下面命令确认：

codex mcp list

4. MCP Server 启动超时

如果你使用 npx 每次临时拉包，首次启动可能慢一些。可以把超时时间调大：

startup_timeout_sec = 60
tool_timeout_sec = 120

更稳定的方式是全局安装 @ant-design/cli，然后使用 antd mcp。

5. 国内网络拉包慢

如果访问 npm registry 较慢，可以临时使用镜像：

npm config set registry https://registry.npmmirror.com
npm install -g @ant-design/cli

如需恢复官方源：

npm config set registry https://registry.npmjs.org

九、完整推荐配置

如果是 Windows + Codex + 全局安装 Ant Design CLI，我推荐使用下面这份配置：

[mcp_servers.antd]
command = "antd.cmd"
args = ["mcp"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 60

如果是 macOS / Linux：

[mcp_servers.antd]
command = "antd"
args = ["mcp"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 60

如果你的项目固定在 Ant Design 5.20.0：

[mcp_servers.antd]
command = "antd"
args = ["mcp", "--version", "5.20.0"]
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 60

十、总结

Ant Design MCP Server 的核心安装流程其实很短：

npm install -g @ant-design/cli
codex mcp add antd -- antd mcp
codex mcp list

真正容易踩坑的地方主要在 Codex 的配置格式和 Windows 命令解析上。Codex 当前使用的是 ~/.codex/config.toml，配置项是 [mcp_servers.antd]；Windows 中如果 antd、npm、npx 无法直接执行，可以分别尝试 antd.cmd、npm.cmd、npx.cmd。

配置成功后，Codex 在编写 Ant Design 页面时就能实时查询官方组件文档、API、示例和版本变更，能明显降低组件用法写错、API 过时、样式 Token 乱猜的问题。