内容
# 自定义 Figma MCP
使用 Codex 或 Claude Code 检查和编辑在 Figma Desktop 中打开的 Figma 文件。
这是一个本地工具。它不使用官方的 Figma MCP、Figma OAuth、Figma API 密钥、文件密钥或 Figma 网页 URL 进行常规编辑。
## 安装
### 1. 安装要求
- Figma Desktop
- Node.js 22.5 或更新版本
- pnpm 10.25 或更新版本
如果缺少 pnpm，`./run.sh` 将尝试使用 Corepack 启用它。
### 2. 启动该项目
打开终端：
```bash
cd /path/to/figma-mcp
./run.sh
```
在使用 Figma MCP 时，请保持此终端窗口打开。
### 3. 添加 Figma 插件
1. 打开 Figma Desktop。
2. 进入 `插件 -> 开发 -> 从清单导入插件...`。
3. 从该项目中选择 `figma-plugin/manifest.json`。
4. 运行 `插件 -> 开发 -> 自定义 Figma MCP Bridge`。
插件应显示“已连接”。
### 4. 连接您的 AI 工具
对于 Codex：
```bash
codex mcp add custom-figma-mcp -- /bin/zsh -lc 'cd /path/to/figma-mcp && node mcp-server/dist/index.js'
```
对于 Claude Code：
```bash
claude mcp add --transport stdio custom-figma-mcp -- /bin/zsh -lc 'cd /path/to/figma-mcp && node mcp-server/dist/index.js'
```
使用该文件夹的实际完整路径。
添加后，请重启 Codex 或 Claude Code。
## 每天使用
1. 在 Figma Desktop 中打开 Figma 文件。
2. 在终端中运行：
```bash
cd /path/to/figma-mcp
./run.sh
```
3. 在 Figma Desktop 中，运行 `插件 -> 开发 -> 自定义 Figma MCP Bridge`。
4. 启动 Codex 或 Claude Code。
5. 要求它检查或编辑打开的 Figma 文件。
## 检查是否有效
运行：
```bash
curl http://localhost:3333/health
```
良好结果：
```json
{
"ok": true,
"pluginConnected": true
}
```
如果 `pluginConnected` 为 `false`，请打开 Figma Desktop，打开您的文件，并运行 `插件 -> 开发 -> 自定义 Figma MCP Bridge`。
## 功能说明
该项目创建一个本地桥接：
```text
Codex / Claude Code
-> 本地 MCP 服务器
-> 本地 WebSocket
-> Figma Desktop 插件
-> 您打开的 Figma 文件
```
AI 工具可以读取和编辑当前在 Figma Desktop 中打开的文件。
它可以创建和更新框架、文本、矩形、组件、自动布局框架、样式、变量和其他支持的 Figma 插件 API 对象。
## 常见问题
### 插件显示重新连接中
1. 确保 `./run.sh` 仍在运行。
2. 在插件中单击“重新连接”。
3. 如果仍然失败，请从 `插件 -> 开发` 关闭并重新运行插件。
### 健康检查显示 pluginConnected 为 false
本地服务器正在运行，但 Figma Desktop 未连接。
打开 Figma Desktop，打开目标文件，并运行 `自定义 Figma MCP Bridge`。
### Codex 或 Claude 不显示工具
在添加 MCP 服务器后，请重启 Codex 或 Claude Code。
在 Codex 或 Claude Code 中，运行 `/mcp` 并查找 `custom-figma-mcp`。
## 更多帮助
- Codex 设置：[docs/codex-setup.md](docs/codex-setup.md)
- Claude Code 设置：[docs/claude-code-setup.md](docs/claude-code-setup.md)
- Figma 插件设置：[docs/figma-setup.md](docs/figma-setup.md)
- 架构详情：[docs/architecture.md](docs/architecture.md)
## 开发人员命令
```bash
pnpm install
pnpm build
pnpm typecheck
pnpm doctor
pnpm test:integration
./run.sh --check
```
