free-figma-mcp

 # Figma 本地 MCP 通过您自己的本地 MCP 服务器运行 Figma。 Figma 本地 MCP 为任何支持 MCP 的 IDE、CLI 或代理提供了一个直接的本地桥梁，通往 Figma Desktop。它公开了官方样式的 Figma MCP 工具名称，但通过您活跃的本地 Figma 文件路由工作，而不是依赖于托管的远程 MCP 会话。 无需 Claude Code 锁定。无需单一 IDE 依赖。无需本地桌面工作流的远程 Figma MCP 配额墙。您的代理与您的本地 MCP 服务器通信，您的本地 MCP 服务器与您的 Figma 插件通信，Figma 更新实际的画布。 > 本项目与 Figma 无关。它是一个本地兼容性桥梁，灵感来自官方 Figma MCP 工作流。 ## 为什么存在 官方远程 MCP 很实用，但本地 Figma 工作需要不同的工具： - 您希望从 Kiro、Cursor、Claude Code、Codex、VS Code、终端代理和任何未来的 MCP 客户端进行 Figma 自动化。 - 您希望继续使用 Figma Desktop 作为真实来源。 - 您希望为检查/写入工作流提供更快的本地往返，这些工作流不需要云文件获取。 - 您希望避免为本地插件支持的工作流设置托管 MCP 速率限制。 - 您希望拥有一个可以检查、扩展、分支、测试和运行的桥梁，而无需等待供应商集成。 Figma 本地 MCP 就是那个桥梁。 ## 什么使它脱颖而出 | 能力 | Figma 本地 MCP | | -------------------------------------------- | ---------------------------------------------------------------- | | 与任何 MCP 客户端一起工作 | 是的。支持 MCP 的 IDE、CLI 和代理都可以使用它。 | | 需要 Claude Code | 不需要。Claude Code 可以使用它，但不是必需的。 | | 直接使用 Figma Desktop | 是的。活动桌面文件是运行时目标。 | | 避免本地工作流的远程 MCP 配额 | 是的。本地工具调用通过您自己的桥梁路由。 | | 多 IDE 友好 | 是的。第一个进程拥有桥梁；后续 IDE 通过它中继。 | | 官方样式工具名称 | 是的。代理看到熟悉的 Figma MCP 样式工具。 | | 本地代码连接样式映射 | 是的。映射存储为本地 JSON。 | | 代理技能和 Kiro 能力 | 包括。 | | 开放且可黑客 | 是的。普通 Node 服务器加上 Figma 插件文件。 | ## 工具表面 服务器公开官方样式的 Figma MCP 工具： - `use_figma` - `get_metadata` - `get_design_context` - `get_screenshot` - `get_variable_defs` - `search_design_system` - `create_design_system_rules` - `get_code_connect_map` - `add_code_connect_map` - `get_code_connect_suggestions` - `send_code_connect_mappings` - `get_figjam` - `generate_diagram` - `generate_figma_design` - `create_new_file` - `whoami` 有关确切的本地行为，请参见 [docs/TOOLS.md](docs/TOOLS.md)。 ## 架构 ```text 任何支持 MCP 的 IDE / CLI / 代理 -> 本地 MCP 标准输入/输出服务器 -> 本地所有者/中继桥梁 -> ws://localhost:3055 -> Figma 插件 UI -> Figma 插件沙盒 -> Figma 插件 API -> 活跃的 Figma Desktop 文档 ``` 本地桥梁是多客户端感知的。如果两个 IDE 启动 MCP 服务器，第一个进程拥有 WebSocket 桥梁，后续进程通过它中继，而不是在端口 `3055` 上崩溃。 ## 安装 对于任何支持 MCP 的 IDE、CLI 或代理，请使用此设置，该设置接受标准的 `mcpServers` 配置。 **1. 从存储库根目录安装** ```bash npm install npm run validate npm run mcp:config ``` `npm run mcp:config` 命令打印一个可以直接复制的配置，使用您的克隆的真实路径。 **2. 将 MCP 服务器添加到您的 IDE** 将生成的 JSON 粘贴到您的 IDE 的 MCP 配置中： ```json { "mcpServers": { "figma-local-mcp": { "command": "node", "args": ["/绝对路径/到/figma-local-mcp/mcp-server/server.js"], "env": {} } } } ``` 您也可以从以下文件开始： - [examples/mcp-config.windows.json](examples/mcp-config.windows.json) - [examples/mcp-config.macos-linux.json](examples/mcp-config.macos-linux.json) - [examples/antigravity-mcp-config.json](examples/antigravity-mcp-config.json) **3. 导入 Figma 插件** 1. 打开 Figma Desktop。 2. 转到 `插件 -> 开发 -> 从清单导入插件`。 3. 选择 `figma-plugin/manifest.json`。 **4. 启动 Figma 会话** 1. 启动您的 IDE 或 CLI MCP 客户端。 2. 在 Figma Desktop 中，运行 `插件 -> 开发 -> Figma 本地 MCP 桥梁`。 3. 在插件窗口中按 `启动`。 4. 打开或创建 Figma 草稿。 5. 要求您的代理调用 `get_metadata`、`get_design_context` 或 `use_figma`。 ## 尝试演示提示 在插件说已连接后，首先进行一个小的烟雾测试： ```text 使用 Figma 本地 MCP 获取我的当前 Figma 文件或选择的元数据。 ``` 然后，从空白的 Figma 草稿开始，验证完整的本地写入流程： ```text 使用 Figma 本地 MCP 在我当前打开的空白 Figma 草稿中构建一个精致的 SaaS 分析仪表板。 要求： - 使用活动 Figma 文件并通过 Figma 本地 MCP 工具本地创建所有内容。 - 创建一个名为“本地 MCP 分析仪表板”的桌面框架，大小为 1440 x 1024。 - 为一个名为“SignalBoard”的虚构使用分析工具设计一个现实的产品仪表板。 - 包括左侧导航栏、顶部命令栏、KPI 卡、折线图区域、使用情况分解部分、最近活动和紧凑的设置面板。 - 使用克制的专业视觉风格，中性表面，蓝色和绿色强调，清晰的层次结构和生产质量的间距。 - 在可行时使用自动布局。 - 创建可读的文本层，现实的数字和分组部分，含义丰富的层名称。 - 创建框架后，使用 get_metadata 总结创建的内容，并使用 get_screenshot 验证结果。 ``` 良好的后续提示： ```text 使用 Figma 本地 MCP 来紧凑间距，对齐仪表板部分并改善视觉层次结构。 ``` ```text 使用 Figma 本地 MCP 添加一个小的引导气泡和左侧导航中的选中状态。 ``` ## 反重力设置 反重力使用相同的标准 `mcpServers` 形状。 打印当前克隆的配置： ```bash npm run mcp:config:antigravity ``` 1. 打开反重力。 2. 打开代理面板。 3. 使用代理面板中的菜单打开 `管理 MCP 服务器`。 4. 打开原始 MCP 配置。 5. 将生成的 JSON 粘贴到 `mcpServers` 配置中。 6. 保存并重启反重力，以便它重新加载 MCP 服务器。 如果您更喜欢直接编辑文件，反重力通常将原始 MCP 配置存储在： ```text ~/.gemini/antigravity/mcp_config.json ``` 您也可以从 [examples/antigravity-mcp-config.json](examples/antigravity-mcp-config.json) 开始，但 `npm run mcp:config:antigravity` 命令更好，因为它为演示打印实际路径。 ## Kiro 能力设置 Kiro 用户可以使用上述标准 MCP 配置，或安装包含额外引导文件的能力包。 1. 打开 Kiro。 2. 从命令调色板打开能力面板。 3. 点击 **添加自定义能力**。 4. 选择 **本地目录**。 5. 输入 `<repo>/powers/local-figma` 的完整路径。 6. 编辑 `~/.kiro/powers/local-figma/mcp.json` 并将 `PLACEHOLDER_SERVER_PATH` 替换为您的本地 `mcp-server/server.js` 路径。 对于 Kiro 能力样式配置，您可以打印一个可以直接复制的代码段： ```bash npm run mcp:config:kiro ``` 该能力包括用于 `use_figma`、设计实现、FigJam、代码连接样式映射、设置和故障排除的引导文件。 ## 插件控制面板 Figma 插件 UI 是为实际使用而构建的： - `启动`：连接到本地桥梁。 - `停止`：将控制权返回给活动的 MCP 调用者，或在没有活动命令时断开桥梁。 - `最小化` / `打开`：折叠或展开面板。 - `聚焦选择`：跳转 Figma 视口到当前选择。 - 日志和命令计数：查看桥梁正在执行的操作。 如果第一个命令记录活动，但后续调用挂起，请重新启动 IDE MCP 服务器并重新运行 Figma 插件桥梁。大型 `use_figma` 脚本可以保持 Figma 插件忙碌，直到 Figma 完成当前脚本。 在测试时，首先在单个 IDE 中启用此 MCP 服务器。多个 IDE 可以通过单个所有者进程中继，但端口 `3055` 上的陈旧所有者可能会使每个中继看起来都已损坏。请参阅 [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md#multiple-ides) 获取重置步骤。 ## 包含代理指导 此存储库包含本地技能和 Kiro 能力文件，以便代理不会盲目生成无效的 Figma 脚本。 技能： - [skills/local-figma-use/SKILL.md](skills/local-figma-use/SKILL.md) - [skills/local-figma-implement-design/SKILL.md](skills/local-figma-implement-design/SKILL.md) - [skills/local-figma-use-figjam/SKILL.md](skills/local-figma-use-figjam/SKILL.md) Kiro 能力： - [powers/local-figma/POWER.md](powers/local-figma/POWER.md) - [powers/local-figma/steering](powers/local-figma/steering) - [powers/local-figma/mcp.json](powers/local-figma/mcp.json) ## 本地与远程 Figma MCP | 远程 Figma MCP | Figma 本地 MCP | | ------------------------------------ | -------------------------------------------------- | | 由 Figma 托管 | 在您的机器上运行 | | 从 Figma 云上下文工作 | 从活动 Figma Desktop 文件工作 | | 可以达到托管的 MCP 限制 | 本地桥梁调用不会消耗托管的 MCP 配额 | | 需要远程服务可用性 | 需要 Figma Desktop 和本地插件 | | 适用于官方云工作流 | 适用于本地 IDE 和桌面自动化 | 这不是每种远程 MCP 功能的替代品。它是代理需要快速、可黑客、与桌面连接的 Figma 访问的本地优先执行路径。 ## 开发 从存储库根目录运行所有内容： ```bash npm install npm run check npm run check:plugin npm test npm run validate ``` 存储库形状： ```text mcp-server/ server.js # 稳定的 MCP 入口点 src/ # 桥梁、工具、内容帮助程序、存储 test/ # Node 测试运行器测试 figma-plugin/ manifest.json code.js # Figma 插件沙盒 ui.html # 插件桥梁控制面板 docs/ examples/ skills/ powers/ ``` ## 诚实的限制 - 本地桥梁在活动 Figma Desktop 文档上运行。 - `fileKey` 参数被接受以兼容，但本地模式不会获取任意远程文件。 - `use_figma` 在 Figma 插件沙盒中执行 JavaScript。只有连接您信任的代理和存储库。 - 停止按钮可以立即解阻塞 MCP 调用者，但大型同步 Figma 脚本需要与 `mcp.shouldStop()` 或 `mcp.throwIfStopped()` 合作。 有关兼容性详细信息，请参见 [docs/OFFICIAL_COMPATIBILITY.md](docs/OFFICIAL_COMPATIBILITY.md)。 ## 记录演示 对于一个短视频演练，上述反重力设置足以在不打开另一个文档的情况下进行记录。更长的检查清单可在 [docs/DEMO_RECORDING.md](docs/DEMO_RECORDING.md) 中找到。 ## 安全 该项目故意允许 MCP 客户端通过本地插件代码检查和修改您的活动 Figma 文档。像具有强大访问权限的本地开发工具一样对待它。请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 MIT。请参阅 [LICENSE](LICENSE)。