F-MCP：基于MCP协议实现AI与Figma本地化协作的完整指南-程序员充电站

1. 项目概述：F-MCP，一个连接AI与Figma的本地化桥梁

如果你是一名设计师或前端开发者，每天在Figma和代码编辑器之间反复横跳，肯定幻想过：能不能让AI直接理解我的设计稿，甚至帮我修改它？或者反过来，我描述一个界面，AI就能在Figma里把它画出来？过去这听起来像科幻，但现在，一个叫F-MCP（Figma MCP Bridge）的开源项目让它变成了现实。

简单说，F-MCP是一个运行在你本地的“翻译官”和“执行者”。它基于Model Context Protocol（MCP）标准，在你常用的AI工具（如Claude Desktop、Cursor、Claude Code）和你正在使用的Figma设计文件之间，建立了一条安全、双向的通信通道。这意味着，你可以在Claude的聊天窗口里，用自然语言直接操作Figma。无论是“提取这个页面的所有颜色变量”、“基于这个按钮组件创建一个新的登录弹窗”，还是“检查当前画板是否符合设计系统的间距规范”，AI都能理解并执行。

最核心的优势是零信任与本地化。所有通信都发生在你的电脑内部，设计数据、API令牌等敏感信息无需上传到任何第三方服务器。这对于处理公司内部机密设计稿或注重隐私的个人项目来说，是至关重要的底线。项目提供了54个精细化的工具和26个预设技能（Skill），覆盖了从设计资产读取、组件管理、设计令牌同步，到最新的原型连线与动画设置等Figma核心工作流。它不是另一个需要你上传文件到云端等待分析的SaaS工具，而是一个深度集成在你现有工作环境中的生产力倍增器。

2. 核心架构与工作原理深度解析

要真正用好F-MCP，理解其背后的运行机制是关键。这能帮助你在遇到连接问题或功能限制时，快速定位原因，而不是盲目尝试。

2.1 MCP协议：AI工具的“USB接口”

MCP（Model Context Protocol）可以理解为AI领域的“USB标准”。在它出现之前，每个AI助手（如Claude、Cursor）想要连接外部工具（如Figma、数据库），都需要开发者为其定制开发独特的插件，过程繁琐且不通用。MCP定义了一套标准的通信协议，让任何符合MCP标准的“服务器”（Server，即工具提供方，如F-MCP）都能被任何支持MCP的“客户端”（Client，即AI应用，如Claude Desktop）发现和调用。

F-MCP本质上就是一个MCP服务器。它启动后，会在本地（通常是localhost:5454）提供一个标准的MCP服务端点。当Claude Desktop或Cursor启动时，它们会读取配置文件，发现并连接这个本地服务。之后，你在AI聊天框中发出的每一个与Figma相关的指令，都会被AI模型转化为对F-MCP服务器上特定工具的调用请求。

2.2 三层架构：工具、技能与编排器

F-MCP的功能组织非常清晰，分为三个层次，由简入繁，适应不同复杂度的任务。

第一层：基础工具（Tools）这是最底层的原子操作，共54个。每个工具对应一个非常具体的Figma操作。例如：

figma_list_components: 列出当前文件中的所有组件。
figma_create_frame: 在指定位置创建一个画框。
figma_set_prototype_connection(v1.9.9+): 在两个节点间建立原型连接。你可以直接要求AI使用某个工具，但更常见的是通过自然语言描述任务，由AI自动选择并组合工具。

第二层：预设技能（Skills）技能是比工具更高级的抽象，共26个。一个技能封装了一个完整的、多步骤的工作流，并包含了让AI更好理解如何执行该任务的上下文、示例和规则。例如：

figma-prototype-flow: 这个技能告诉AI如何智能地建立页面间的原型流程，包括识别可点击元素、选择合适的触发器和动画。
design-system-audit: 这个技能指导AI如何系统性地检查设计稿对设计规范的遵守情况。技能以文件形式存在，可以被“注入”到AI的上下文中，极大地提升了AI处理复杂任务的准确性和效率。

第三层：流程编排器（Orchestrators）这是最高级的自动化层。编排器是预先编写好的、端到端的自动化脚本或智能体（Agent），用于处理极其复杂的任务。例如，一个“设计系统同步编排器”可以：1）扫描代码仓库中的设计令牌（Design Tokens）；2）读取Figma中的变量（Variables）；3）对比差异；4）在Figma中批量创建或更新变量；5）生成变更报告。在Claude Code中，项目利用其子智能体（Sub-agent）能力，将这类重型任务分配给独立的AI实例执行，避免干扰主聊天会话的上下文。

2.3 连接模式：Claude Code vs. Claude Desktop

这是实际操作中最重要的区别，很多困惑都源于此。

Claude Code：功能完整的开发环境Claude Code是一个独立的、面向开发的AI应用。F-MCP的安装脚本是为Claude Code量身定制的，因此它能获得最完整的支持：

子智能体（Sub-agent）：可以派发独立任务，适合长时间、高复杂度的编排任务。
钩子（Hooks）：可以在任务执行前后或会话开始时自动运行特定逻辑。
Slash Commands：支持像/ds-sync这样的快捷命令。
自动发现：能自动加载plugin.json和.claude/CLAUDE.md等配置文件。简单说，Claude Code是“完全体”体验，适合深度集成和自动化。

Claude Desktop：面向日常聊天的优化体验Claude Desktop是我们日常对话最常用的客户端。它不支持上述高级特性，因此F-MCP采用了不同的策略来保证功能：

阻塞式设计系统检查：当AI试图执行一个可能违反设计规范的操作时（如使用非标准色），插件会直接发回一个_DESIGN_SYSTEM_VIOLATIONS_BLOCKING信号，阻止操作并给出修改建议。
运行时审查工具：提供figma_scan_ds_compliance工具，供你手动或让AI主动进行合规性扫描。
智能截图策略：为了节省宝贵的上下文窗口，它会根据情况选择发送完整截图、区域截图、Base64编码或仅文字摘要。
探索预算：限制AI对文件结构的“探索”调用次数（如连续列出所有页面、所有组件），超过12次后会触发阻塞，防止AI无意义地消耗资源。
项目知识库：将关键的Skill文件预先上传到Claude Desktop的“项目知识”中，为AI提供必要的上下文。

实操心得：对于绝大多数日常设计协作和修改任务，Claude Desktop完全够用，且交互更自然。只有当你需要运行复杂的、多步骤的自动化同步脚本时，才需要切换到Claude Code环境。安装只需一次，之后两个客户端可以按需使用。

3. 从零开始：详细安装与配置指南

虽然README说只需5分钟，但为了确保一次成功，避免踩坑，我们展开每个步骤。

3.1 前期准备与环境检查

在开始安装前，请确认以下几点：

Figma桌面端或网页端：确保已登录账号，并且有一个可以打开的设计文件（即使是空白文件也行）。插件需要在一个活跃的Figma编辑器中运行。
Node.js环境：F-MCP基于Node.js，但如果你通过Claude Code安装，它会自动处理。不过，预先在终端输入node -v检查一下也无妨，建议版本在18以上。
网络与权限：安装过程需要从GitHub和npm下载资源。确保你的网络能正常访问这些服务。在macOS上，安装过程中可能会请求“辅助功能”或“自动化”权限，这是为了允许脚本自动操作部分系统设置，务必点击“允许”。

3.2 逐步安装流程

步骤一：获取Claude Code前往 Anthropic 官网下载 Claude Code。这是安装环节的“钥匙”。安装完成后打开它，你会看到一个类似终端（命令行）的界面。

步骤二：执行一键安装命令在Claude Code的输入框中，直接粘贴以下命令并回车：

https://github.com/atezer/FMCP bu repoyu kur

或者使用英文指令（效果相同）：

install the repo https://github.com/atezer/FMCP

接下来，Claude Code会开始表演：

克隆仓库：将F-MCP的代码下载到你的本地（通常在用户目录下的某个位置）。
依赖安装：自动运行npm install，安装项目所需的所有Node.js模块。
构建项目：运行构建脚本，生成可执行文件。
配置集成：自动修改或创建Claude Code、Cursor等客户端的MCP配置文件（mcp.json或claude_desktop_config.json），将F-MCP服务器地址添加进去。在这个过程中，你可能会被要求输入电脑的登录密码。这是为了授予脚本修改系统配置文件的权限（如写入应用程序支持目录），属于正常且必要的步骤。

步骤三：重启与验证当Claude Code显示“Kurulum tamamlandı”（安装完成）或类似提示后：

完全关闭Claude Code。
重新打开Claude Code。这一步至关重要，是为了让重新加载更新后的配置文件。
打开Figma，在一个设计文件中，点击顶部菜单栏的Plugins→Development→Import plugin from manifest...。
在文件选择器中，你需要导航到F-MCP的安装目录。如果你不知道具体路径，可以在重新打开的Claude Code中询问：“F-MCP插件manifest文件在哪里？”。通常路径会像~/some-path/FMCP/f-mcp-plugin/manifest.json。选择这个manifest.json文件。
导入成功后，在Plugins菜单下（通常不在Development里了）你应该能看到F-MCP ATezer Bridge。点击它，会弹出一个插件窗口。如果一切正常，窗口内会显示一个绿色的“Ready”状态。

步骤四：在Claude Desktop中验证

打开Claude Desktop应用（注意，不是Claude Code，也不是网页版）。
新建或打开一个对话。
直接尝试提问：“当前打开的Figma文件里有哪些页面？”。如果AI能够回应并列出页面，说明连接成功。如果AI表示不理解或无法连接，请检查下一步的故障排查。

3.3 可选但推荐：配置Figma个人访问令牌

没有令牌，F-MCP的核心读写功能完全正常。但令牌像一把“万能钥匙”，能解锁Figma API的全部能力，特别是读取评论、版本历史，以及更高效的资源导出。

获取令牌：

登录 Figma开发者后台。
在Personal Access Tokens部分，点击Create new token。
为令牌起个名字，例如 “F-MCP Local”。
权限范围（Scopes）建议全选，以确保所有工具都能正常工作。
生成后，立即复制那一长串字符。

在插件中配置：

在Figma中打开F-MCP插件窗口。
找到Advanced选项卡或折叠区域。
将复制的令牌粘贴到API Token输入框。
在下方选择令牌的有效期（如90天）。插件会将其加密后存储在本地。
点击保存或确认。

安全警告：这个令牌拥有对你Figma账户的广泛访问权。F-MCP将其存储在本地是安全的。但切勿将此令牌分享给他人或提交到公开的代码仓库。如果怀疑泄露，立即回开发者后台撤销它。

4. 核心应用场景与实操演示

安装配置完毕，我们来实战。以下场景覆盖了从简单到进阶的日常需求。

4.1 场景一：设计资产分析与提取

你接手一个旧项目，需要快速理解其设计结构。

你可以对Claude说：“请分析当前打开的Figma文件，给我一份设计资产报告，包括：1. 页面和主要画板数量；2. 使用的颜色和字体样式统计；3. 所有组件及其使用次数。”

AI背后的操作：

调用figma_list_pages和figma_list_frames获取结构。
调用figma_list_colors和figma_list_text_styles获取样式。
调用figma_list_components获取组件，并可能结合figma_get_component分析详情。
组织信息，生成一份清晰的Markdown格式报告回复给你。

进阶用法——提取设计令牌：“将这个文件中的所有颜色样式导出为CSS自定义属性格式的Design Tokens。” AI会使用figma_list_colors获取数据，然后格式化成：

:root { --primary-500: #0a7cff; --gray-200: #e5e7eb; /* ... */ }

4.2 场景二：设计系统合规性审查

确保设计稿符合团队规范，是设计师和开发者的共同痛点。

操作：在Claude Desktop中，你可以直接说：“检查当前画板中的所有文本元素，看它们的字体、字号、行高是否符合我们的设计系统规范？如有违规，请列出详情。”

AI的执行逻辑：

调用figma_scan_ds_compliance工具，该工具会扫描选中节点或整个画板。
根据内置或你通过Skill定义的规则（例如：“标题使用字体Inter，字号不小于20px”）进行比对。
返回一个详细的审查报告，指出哪个图层违反了哪条规则，并给出修改建议。

实操心得：为了获得最佳审查效果，你需要提前“教会”AI你的设计系统。最简单的方法是在对话开始时，将设计系统文档（如Notion链接、Markdown文件）作为附件上传给Claude，或者将关键规则整理成文本粘贴进去。这样AI在调用审查工具时，就有了判断的依据。

4.3 场景三：AI辅助设计与内容生成

这是最体现价值的地方：从想法到可视化的快速原型。

操作：“在页面‘Home’的右侧，创建一个新的画板（Frame），尺寸为iPhone 15（390x844）。在里面设计一个用户个人资料卡片的头像区域，包含圆形头像、用户名和‘编辑资料’按钮。使用我们设计系统中的主色和卡片阴影。”

AI的执行步骤：

figma_create_frame：创建指定尺寸和位置的画板。
figma_create_ellipse+figma_fill_color：创建并填充圆形作为头像。
figma_create_text+figma_set_text_style：创建用户名文本并应用预设的文本样式。
figma_create_rectangle+figma_create_text：创建按钮背景和文字。
figma_set_fill_color：为按钮应用主色。
figma_set_effect：为整个卡片添加阴影效果。

整个过程无需你手动拖动一个图层。如果AI对某些样式不确定，它会主动向你提问，比如“主色的具体色值是什么？”。

4.4 场景四：设计到代码的桥梁（v1.9.8+）

对于前端开发者，这个功能堪称神器。它利用Figma的“Code Connect”等特性，建立设计与代码组件的映射。

操作：“为我当前选中的这个‘数据表格’组件，生成设计上下文，包括它使用的变量和对应的代码组件信息。”

AI会调用figma_use工具：

意图（intent）：design_context
结果：AI会返回该组件的构成信息（如图层结构）、所使用的颜色/字体变量（Tokens），以及通过Code Connect关联到的React/Vue组件名称和Props。这为后续生成高保真代码提供了坚实基础。

4.5 场景五：自动化原型连线与交互（v1.9.9+）

手动在Figma里拖拽连接线制作原型非常耗时。现在可以让AI代劳。

操作：“为‘登录页’和‘主页’这两个画板建立原型连接。触发条件是点击登录按钮，使用‘滑动进入’的过渡动画，方向从右向左。”

AI会调用一系列新工具：

figma_get_prototype_connections：先查看现有连接，避免重复。
figma_create_prototype_connection：在登录按钮（起始节点）和主页画板（目标节点）之间建立连接。
figma_create_interaction：为这个连接配置交互细节：触发器（ON_CLICK）、动作（NAVIGATE_TO）、过渡动画（SLIDE_IN）、方向（LEFT）。
figma_set_flow_starting_point：如果需要，将登录页设置为流程的起点。

你甚至可以描述更复杂的流程：“创建一个从欢迎页到登录页，再到忘记密码页的完整用户流程，所有过渡都用智能动画。” AI会利用figma-prototype-flow这个Skill，智能地识别页面中的按钮和链接，批量创建连接。

5. 常见问题排查与进阶技巧

即使安装顺利，在实际使用中也可能遇到一些小问题。以下是经过实战积累的排查清单和提升效率的技巧。

5.1 连接类问题

问题：Figma插件一直显示“Connecting...”或“No server”。

首要检查：确保你的AI客户端（Claude Desktop或Cursor）已经启动并处于活跃状态。F-MCP服务器是随AI客户端启动的，如果AI没开，插件自然找不到服务。
检查端口占用：有时旧的F-MCP进程没有正确退出。按照README建议，在终端运行项目提供的清理脚本：
```
# 导航到FMCP项目目录后执行 bash scripts/cleanup-ports.sh
```
这个脚本会安全地关闭5454到5470端口上与FMCP相关的残留进程。
重新导入插件：Figma可能会缓存旧的插件代码。前往Plugins → Development → Manage plugins in development，找到F-MCP ATezer Bridge并移除。然后重新通过Import plugin from manifest...导入一次。

问题：在Claude Desktop里说话，AI不响应Figma相关指令。

确认配置：在Claude Desktop中，点击左上角你的头像，进入Settings→Developer。查看MCP配置里是否包含了F-MCP服务器的条目。安装脚本应该已自动完成，但手动确认一下更保险。
重启大法：完全退出Claude Desktop和Figma，再重新打开。这能解决90%的上下文加载问题。
明确指令：尝试更具体的指令，如“使用F-MCP工具列出当前Figma文件的页面”，而不是笼统的“看看我的设计稿”。这有助于AI准确路由你的请求。

5.2 功能与性能问题

问题：AI执行操作很慢，或者中途“失忆”。

上下文过载：Claude Desktop有上下文窗口限制。如果Figma文件非常复杂（数百个画板、数千个图层），AI请求一个完整截图或大量节点信息时，可能会消耗大量上下文。F-MCP的“智能截图”和“探索预算”机制正是为了缓解此问题。你可以尝试让AI只分析当前页面或选中区域。
网络问题（本地）：虽然数据不走互联网，但本地WebSocket通信也可能受防火墙或安全软件影响。确保没有软件阻止localhost:5454端口的通信。

问题：某些工具（如设置API Token的选项）在插件窗口里找不到。

插件版本：确保你运行的是最新版本的F-MCP插件。在Figma的插件开发面板中，有时需要手动“重新加载”插件以获取更新。
查看高级选项：部分设置（如API Token输入）可能在插件窗口的“Advanced”折叠面板下，需要点击展开。

5.3 提升协作效率的进阶技巧

为常用任务创建快捷指令：在Cursor或Claude Code中，你可以将复杂的F-MCP操作流封装成自定义命令（Command）或代码片段（Snippet）。例如，一个名为“/audit-page”的命令，可以自动触发设计系统审查并生成报告。
结合项目知识库：在Claude Desktop中，将你的设计系统文档、品牌规范PDF等文件上传到“项目知识库”。当AI处理Figma任务时，它会自动参考这些知识，做出的判断和设计会更精准。
分阶段处理大型任务：对于“重新设计整个仪表盘”这种宏大任务，不要一次性提出。分解为：“1. 分析现有布局和组件；2. 在侧边栏新建一个页面‘Redesign’；3. 基于分析，在‘Redesign’页面创建新的布局框架；4. 将旧页面的核心内容迁移到新框架；5. 应用新的视觉样式。” 分步引导AI，成功率更高。
善用“纠正”与“微调”：AI生成的结果可能不完全符合预期。你可以直接指出：“把刚才创建的标题字体从Inter换成SF Pro”，“把那个按钮再往右移动20像素”。AI能理解这些基于上下文的修正指令，并调用相应的工具（figma_set_text_style,figma_set_position）进行修改。这是一个交互式的、对话式的设计过程。
定期更新：F-MCP项目迭代迅速，特别是Figma API更新后。定期在Claude Code里运行“F-MCP'yi güncelle”（更新F-MCP）指令，可以确保你始终拥有最新功能和Bug修复。

这个工具的核心价值在于，它将AI从一个被动的问答机器，变成了一个能直接在你工作环境里动手操作的协作者。它不替代设计师或开发者的专业判断，而是将我们从重复、机械的操作中解放出来，让我们能更专注于创造和决策。开始尝试从一个小任务入手，比如“给这个页面所有按钮加个悬停状态”，你会立刻感受到这种工作流带来的变化。