Codex Local Bridge

v0.3.0 · MIT · 独立社区项目 / Unofficial community project

让本地支持 MCP 的助手连接 Figma Desktop，读取文档、页面和选区，编辑原生图层/组件，并导出 PNG/SVG。无需 Figma API 密钥，无 npm 运行依赖。不是 OpenAI 或 Figma 官方插件，也不属于其认证产品。

本地服务无身份鉴权，监听 localhost:37821。能访问本机服务的程序可读写已连接文件。来源检查不是身份验证。请先阅读 安全说明、隐私说明 和 免责声明，重要设计先复制或保留版本历史。

安装与启动

1. 安装 Node.js 22 或更新的受支持版本，并确保 node 在 PATH 中。

2. 下载 Release ZIP 并校验同页 SHA256SUMS，或克隆本仓库。保留目录结构。

3. 支持 Agent Plugins 的客户端使用根目录 plugin.json 和 mcp.json；旧 Codex 客户端可使用 .codex-plugin/plugin.json 和 .mcp.json。${PLUGIN_ROOT} 必须由宿主展开。不同宿主安装入口不同，本仓库不自动修改你的全局配置。

4. 若宿主只支持普通 MCP 配置，使用下例，将目录替换为实际绝对路径。PLUGIN_ROOT 是插件宿主变量，不是 Node 自动展开的系统变量。

5. 在 Figma Desktop 中选择 Plugins → Development → Import plugin from manifest，导入本仓库 figma/manifest.json，运行插件并保持窗口打开。

6. 调用 local_figma_connect。只有成功回读目标文档才算连接完成；服务运行不代表文件已连接。

{
  "mcpServers": {
    "codex-local-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/codex-local-bridge/mcp-server.mjs"]
    }
  }
}

Windows JSON 路径可用正斜杠，如 C:/path/to/codex-local-bridge/mcp-server.mjs。若宿主无法找到 node，将 command 改成你实际的 Node 可执行文件路径，不要复制别人的用户目录。

MCP 调用可自动启动服务。手动启动和停止便于管理：

node bridge-server.mjs
# 在该终端按 Ctrl+C 停止；Figma 侧也应关闭插件窗口。

自动启动的后台进程可能在助手会话结束后继续运行。不要按端口盲目终止未知进程；需要确定生命周期时采用手动启动方式。升级后重启服务、重新导入对应 manifest，并在每个文件中重开插件，确认 /health.serverVersion 与 bridge-capabilities.version。

Related MCP server: figma-ui-mcp

工具和能力

六个 MCP 工具均为读取/导出：local_figma_connect、local_figma_status、local_figma_document、local_figma_pages、local_figma_node、local_figma_export。

本地 HTTP /command 另支持结构化写入、导入图片与设计系统操作。没有任意 JavaScript 执行接口。详细边界见 API。创建字体、页面、变量与组件可能直接修改当前文件；设计系统操作不是全局事务。

每份文件分别运行插件。连接列表返回 connectionId，多连接时必须显式指定，不能猜目标。同一连接串行，不同连接可并行；无跨文件事务。连接 ID 是路由标识，不是密码。

读超时默认15秒；构建、设计系统、导入图片和导出60秒。已派发超时会锁定该连接，等待迟到结果。先核对 /health 中 progress、lastResult 和画布，不要直接重放写入；重启不撤销已执行的修改。

验证与已知限制

npm run check
npm test

测试使用本机隔离测试端口、模拟 Figma API 和 JSON-RPC，不需要打开设计文件，不导出真实设计。它们覆盖连接隔离、超时锁定/恢复、回传重试、字体预加载、构建回滚、来源/请求体限制及 MCP 行为；不证明所有 Figma API 或宿主版本均兼容。docs/TESTING.md 说明真实文件的人工烟测方法。

不包含设计项目截图、源设计、账号配置、第三方字体、AI 模型或服务额度。读取内容若交给云端助手处理，可能离开本机；“本地桥接”不等于整个 AI 工作流离线。详见 隐私说明。

许可、贡献和反馈

MIT License 适用于有权许可的仓库代码与文本；第三方软件、字体、设计和商标不由此取得授权。免责声明 不为 MIT 增加许可限制。

欢迎提交公开的最小复现及版本号。不要在 Issue、日志或截图中附带密钥、客户设计、文件 key、连接信息或个人路径。安全问题先按 SECURITY.md 处理。改动后运行测试，不要提交真实设计数据。