claude-talk-to-figma-mcp

🚀 Claude Talk to Figma MCP

Claude Talk to Figma MCP 是一款模型上下文协议（MCP）插件，它允许 Claude Desktop 及其他 AI 工具（如 GitHub Copilot、Cursor 等）直接与 Figma 进行交互，从而实现强大的 AI 辅助设计功能。

🚀 快速开始

安装

前提条件

• 已安装 Claude Desktop 或 Cursor、Figma Desktop 以及 Bun。

安装步骤

git clone https://github.com/arinspunk/claude-talk-to-figma-mcp.git
cd claude-talk-to-figma-mcp
bun install

• macOS/Linux：执行 bun run build。
• Windows：执行 bun run build:win。

AI 客户端配置

选项 1：DXT 包（仅适用于 Claude Desktop）

1. 下载：从 releases 下载最新的 claude-talk-to-figma-mcp.dxt 文件。
2. 安装：双击 .dxt 文件，Claude Desktop 将自动完成安装。

选项 2：JSON（适用于 Claude Desktop 和 Cursor）

• Claude Desktop：运行 bun run configure-claude，然后重启 Claude Desktop。
• Cursor：
  1. 打开 Cursor 设置，选择“Tools & Integrations”。
  2. 点击“New MCP Server”以打开 mcp.json 配置文件（截图）。
  3. 添加以下配置：

  {
    "mcpServers": {
      "ClaudeTalkToFigma": {
        "command": "bunx",
        "args": ["claude-talk-to-figma-mcp@latest"]
      }
    }
  }
  

  4. 保存文件（截图）。

设置 Figma 插件（所有方法均需此步骤）

在 Figma 中，通过菜单选择“Plugins”→“Development”，导入 src/claude_mcp_plugin/manifest.json 文件。

首次连接

1. 启动服务器：执行 bun socket，并在 http://localhost:3055/status 验证服务器是否正常运行。
2. 连接插件：在 Figma 中打开 Claude MCP 插件，复制频道 ID。
3. 测试：向你的 AI 客户端发送指令：“Talk to Figma, channel {channel-ID}”。

✅ 成功标志：AI 确认连接成功后，你即可开始设计！

✨ 主要特性

工作原理

Claude Desktop ↔ MCP Server ↔ WebSocket Server ↔ Figma Plugin

• 简单易用：Claude 发送设计指令，Figma 实时执行。
• 双向交互：从 Figma 获取信息，创建/修改元素，管理组件。

核心功能

• 文档交互：分析设计、获取选择内容、导出资源。
• 元素创建：创建具有完整样式控制的形状、文本和框架。
• 智能修改：调整颜色、效果、自动布局和响应式设计。
• 文本处理：支持高级排版、字体加载和文本扫描。
• 组件集成：集成本地和团队库组件。

📦 安装指南

构建 DXT 包（开发者适用）

若要创建自己的 DXT 包，可执行以下命令：

npm run build:dxt    # 构建 TypeScript 并打包 DXT

此命令将生成 claude-talk-to-figma-mcp.dxt 文件，可用于分发。

💻 使用示例

开始 AI 设计

1. 让 Claude 成为 UX 专家：使用 此提示 🎨
2. 连接到项目：发送指令“Talk to Figma, channel {channel-ID}”。
3. 开始设计：例如，发送指令“Create a mobile app login screen with modern styling”。

有效提示示例

✅ 推荐："Create a dashboard with a sidebar navigation, header with user profile, and main content area with card-based metrics"

✅ 推荐："Redesign this button component with hover states and better contrast ratios"

❌ 避免："Make it look nice"（过于模糊）

📚 详细文档

命令参考

📄 文档工具

| 命令 | 用途 | 示例用法 | |------|------|----------| | get_document_info | 文档分析 | 获取项目概述 | | get_selection | 获取当前选择内容 | 查看当前选中的元素 | | get_node_info | 获取元素详细信息 | 检查特定组件 | | get_nodes_info | 获取多个元素信息 | 批量检查元素 | | scan_text_nodes | 查找所有文本 | 进行文本审核和更新 | | get_styles | 获取文档样式 | 审核颜色和文本样式 | | join_channel | 连接到 Figma | 建立通信 | | export_node_as_image | 导出资源 | 生成设计资源 |

🔧 创建工具

| 命令 | 用途 | 示例用法 | |------|------|----------| | create_rectangle | 创建基本形状 | 创建按钮、背景等 | | create_frame | 创建布局容器 | 创建页面部分、卡片等 | | create_text | 创建文本元素 | 创建标题、标签等 | | create_ellipse | 创建圆形/椭圆形 | 创建头像、图标等 | | create_polygon | 创建多边形 | 创建自定义几何元素 | | create_star | 创建星形 | 创建装饰元素 | | clone_node | 复制元素 | 复制现有设计 | | group_nodes | 组织元素 | 对组件进行分组 | | ungroup_nodes | 拆分组 | 拆分组件 | | insert_child | 嵌套元素 | 创建层次结构 | | flatten_node | 矢量操作 | 进行布尔运算 |

✏️ 修改工具

| 命令 | 用途 | 示例用法 | |------|------|----------| | set_fill_color | 设置元素颜色 | 应用品牌颜色 | | set_stroke_color | 设置边框颜色 | 调整轮廓样式 | | move_node | 定位元素 | 调整布局 | | resize_node | 调整元素大小 | 实现响应式缩放 | | delete_node | 删除元素 | 清理设计 | | set_corner_radius | 设置圆角 | 实现现代 UI 样式 | | set_auto_layout | 设置类似 Flexbox 的布局 | 调整组件间距 | | set_effects | 设置阴影/模糊效果 | 提升视觉效果 | | set_effect_style_id | 应用效果样式 | 保持一致的阴影样式 |

📝 文本工具

| 命令 | 用途 | 示例用法 | |------|------|----------| | set_text_content | 更新文本内容 | 修改文案 | | set_multiple_text_contents | 批量更新文本内容 | 批量编辑元素 | | set_font_name | 设置排版字体 | 应用品牌字体 | | set_font_size | 设置文本大小 | 创建层次结构 | | set_font_weight | 设置文本粗细 | 实现粗体/细体变化 | | set_letter_spacing | 设置字符间距 | 微调排版 | | set_line_height | 设置垂直间距 | 提高文本可读性 | | set_paragraph_spacing | 设置段落间距 | 构建内容结构 | | set_text_case | 转换大小写 | 实现大写/小写/标题大小写 | | set_text_decoration | 设置文本样式 | 添加下划线/删除线 | | get_styled_text_segments | 分析文本 | 检查富文本 | | load_font_async | 加载字体 | 访问自定义字体 |

🎨 组件工具

| 命令 | 用途 | 示例用法 | |------|------|----------| | get_local_components | 获取项目组件 | 审核设计系统 | | get_remote_components | 获取团队库组件 | 访问共享组件 | | create_component_instance | 使用组件 | 创建一致的 UI 元素 |

🔧 技术细节

架构剖析

+----------------+     +-------+     +---------------+     +---------------+
|                |     |       |     |               |     |               |
| Claude Desktop |<--->|  MCP  |<--->| WebSocket Srv |<--->| Figma Plugin  |
|   (AI Agent)   |     |       |     |  (Port 3055)  |     |  (UI Plugin)  |
|                |     |       |     |               |     |               |
+----------------+     +-------+     +---------------+     +---------------+

设计原则：

• MCP Server：负责业务逻辑、验证和默认值设置。
• WebSocket Server：负责消息路由和协议转换。
• Figma Plugin：在 Figma 上下文中纯粹执行命令。

优势：

• 职责清晰分离。
• 易于测试和维护。
• 可扩展架构，便于添加更多工具。

项目结构

src/
  talk_to_figma_mcp/     # MCP Server 实现
    server.ts            # 主入口点
    tools/               # 按功能划分的工具类别
      document-tools.ts  # 文档交互工具
      creation-tools.ts  # 形状和元素创建工具
      modification-tools.ts # 属性修改工具
      text-tools.ts      # 文本处理工具
    utils/               # 共享实用工具
    types/               # TypeScript 定义
  claude_mcp_plugin/     # Figma 插件
    code.js              # 插件实现
    manifest.json        # 插件配置

贡献指南

1. 分叉并创建分支：执行 git checkout -b feature/amazing-feature。
2. 代码规范：遵循现有的 TypeScript 模式。
3. 测试：为新功能添加测试。
4. 文档：更新相关文档。
5. 拉取请求：清晰描述更改内容。

近期贡献者

• Taylor Smits - 实现 DXT 包支持、自动化 CI/CD 工作流并改进测试（PR #17，PR #13，PR #14）。
• easyhak - 修复了在 Windows 操作系统上构建脚本无法正常工作的问题（PR #10）。

🧪 测试与质量保证

自动化测试

bun run test            # 运行所有测试
bun run test:watch      # 开启监听模式
bun run test:coverage   # 生成覆盖率报告

集成测试

bun run test:integration  # 进行端到端的引导式测试

手动验证清单

• [ ] WebSocket 服务器在端口 3055 上启动。
• [ ] Figma 插件成功连接并生成频道 ID。
• [ ] AI 工具识别“ClaudeTalkToFigma”MCP（如 Claude Desktop、Cursor 等）。
• [ ] 基本命令执行成功（如创建矩形、更改颜色）。
• [ ] 错误处理正常（如处理无效命令、超时等）。
• [ ] AI 工具与 Figma 之间的频道通信正常。

🐛 故障排除与支持

连接问题

• “无法连接到 WebSocket”：确保 bun socket 正在运行。
• “未找到插件”：验证在 Figma 开发设置中是否正确导入插件。
• “MCP 不可用”：
  • Claude Desktop：运行 bun run configure-claude 并重启 Claude。
  • Cursor IDE：检查 mcp.json 文件中的 MCP 配置。
  • 其他 AI 工具：验证 MCP 集成设置。

执行问题

• “命令执行失败”：检查 Figma 开发控制台中的错误信息。
• “未找到字体”：使用 load_font_async 验证字体可用性。
• “权限被拒绝”：确保你具有编辑 Figma 文档的权限。
• “超时错误”：复杂操作可能需要重试。

性能问题

• 响应缓慢：大型文档可能需要更多处理时间。
• 内存使用过高：关闭未使用的 Figma 标签，必要时重启。
• WebSocket 断开连接：服务器会自动重连，若问题持续存在，可尝试重启。

常见解决方案

1. 重启顺序：停止服务器 → 关闭 AI 工具 → 重新启动两者。
2. 彻底重装：删除 node_modules 文件夹，执行 bun install 和 bun run build。
3. 检查日志：服务器终端会显示详细的错误信息。
4. 更新字体：某些团队字体需要在 Figma 中手动加载。
5. 检查配置：验证 AI 工具设置中的 MCP 配置。
6. 解决端口冲突：确保端口 3055 未被其他应用程序占用。

📋 版本历史

当前版本：0.6.0

• 🚀 DXT 包支持：可通过 Claude Desktop 的扩展管理器实现一键安装（感谢 Taylor Smits - PR #17）。
• 📦 自动化分发：使用 GitHub Actions 工作流自动生成 DXT 包并上传发布。
• ⚡ 增强用户体验：将最终用户的安装时间从 15 - 30 分钟缩短至 2 - 5 分钟。
• 🔧 开发者工具：新增用于 DXT 打包的构建脚本（npm run build:dxt，npm run pack）。

完整版本历史请参阅 CHANGELOG.md。

📄 许可证

许可证：本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

作者：

• Xúlio Zé - Claude 适配 - GitHub
• Sonny Lazuardi - 原始实现 - GitHub

致谢：

• Anthropic 团队提供的 Claude 和模型上下文协议。
• Figma 社区提供的优秀插件 API。
• Bun 团队提供的快速 JavaScript 运行时。