Claude Talk To Figma MCP

🚀 Claude Talk to Figma MCP

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

⚠️ 重要提示

本项目基于 Sonny Lazuardi 的 cursor-talk-to-figma-mcp 开发。它已适配 Claude Desktop 并扩展了其他工具。原作者为 Sonny Lazuardi，在此表示感谢 ❤️

🚀 快速开始

本插件能让 AI 工具与 Figma 无缝对接，实现高效的设计协作。下面为你详细介绍使用前的安装和配置步骤。

⚡ 安装指南

前提条件

• 安装 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 设置 → 工具与集成。
  2. 点击“New MCP Server”打开 mcp.json 配置文件（截图）。
  3. 添加以下配置：

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

  4. 保存文件（截图）。

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

在 Figma 中导入 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 获取信息，创建/修改元素，管理组件。

核心能力

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

💻 使用示例

开启 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"（过于模糊）

📚 详细文档

📄 文档工具

🔧 创建工具

✏️ 修改工具

📝 文本工具

🎨 组件工具

构建 DXT 包（开发者适用）

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

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

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

🔧 技术细节

自动化测试

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 未被其他应用占用。

🏗️ 高级主题

架构深入解析

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

设计原则：

• MCP 服务器：处理业务逻辑、验证和设置默认值。
• WebSocket 服务器：负责消息路由和协议转换。
• Figma 插件：在 Figma 环境中执行命令。

优势：

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

项目结构

src/
  talk_to_figma_mcp/     # MCP 服务器实现
    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. Fork 仓库并创建分支：运行 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）。

📋 版本历史

当前版本：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 运行时。