Figma MCP Server

Figma MCP Server

一个 Model Context Protocol（MCP）服务，通过 Claude 和其他兼容 MCP 的客户端集成 Figma API。目前支持对 Figma 文件和项目的只读访问；其服务端架构能够支持更高级的设计令牌和主题管理功能（有待 Figma API 增强或插件开发）。

项目状态

当前进展

• ✅ 核心实现：已成功构建一个遵循 Model Context Protocol（MCP）的 TypeScript 服务
• ✅ Claude Desktop 集成：已测试，可与 Claude Desktop 配合使用
• ✅ 读取操作：用于访问 Figma 文件的 get-file 和 list-files 工具已正常运行
• ✅ 服务架构：已实现缓存系统、错误处理和统计监控
• ✅ 传输协议：支持 stdio 和 SSE 两种传输机制

潜在的完整功能

该服务在设计时已编写代码支持以下功能（目前受 API 限制）：

• 变量管理：创建、读取、更新和删除设计令牌（变量）
• 引用处理：创建并验证令牌之间的关系
• 主题管理：创建具有多种模式（例如浅色／深色）的主题
• 依赖分析：检测并防止循环引用
• 批量操作：批量处理变量和主题

通过开发 Figma 插件或扩展 API 访问权限，即可全面启用这些功能。

功能

• 🔑 使用 Figma API 进行安全身份验证
• 📁 文件操作（读取、列出）
• 🎨 设计系统管理
  • 变量创建和管理
  • 主题创建和配置
  • 引用处理和验证
• 🚀 性能优化
  • LRU 缓存
  • 速率限制处理
  • 连接池
• 📊 全面监控
  • 健康检查
  • 使用统计
  • 错误追踪

前置要求

• Node.js 18.x 或更高版本
• 具有适当权限的 Figma 访问令牌
• 对 MCP（Model Context Protocol）有基本了解

安装

npm install figma-mcp-server

配置

1. 根据 .env.example 创建 .env 文件：

# Figma API Access Token
FIGMA_ACCESS_TOKEN=your_figma_token

# Server Configuration
MCP_SERVER_PORT=3000

# Debug Configuration
DEBUG=figma-mcp:*

2. 集成 Claude Desktop：

可在 Claude Desktop 配置文件中配置该服务：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/figma-mcp-server/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

重要说明：

• 使用绝对路径，而非相对路径
• 在 Windows 上，路径中使用双反斜杠（\\）
• 更改配置后，请重启 Claude Desktop

使用方法

基本用法

import { startServer } from 'figma-mcp-server';

const server = await startServer(process.env.FIGMA_ACCESS_TOKEN);

可用工具

1. get-file

   • 获取 Figma 文件详情

   {
     "name": "get-file",
     "arguments": {
       "fileKey": "your_file_key"
     }
   }
   

2. list-files

   • 列出 Figma 项目中的文件

   {
     "name": "list-files",
     "arguments": {
       "projectId": "your_project_id"
     }
   }
   

3. create-variables

   • 创建设计系统变量

   {
     "name": "create-variables",
     "arguments": {
       "fileKey": "your_file_key",
       "variables": [
         {
           "name": "primary-color",
           "type": "COLOR",
           "value": "#0066FF"
         }
       ]
     }
   }
   

4. create-theme

   • 创建和配置主题

   {
     "name": "create-theme",
     "arguments": {
       "fileKey": "your_file_key",
       "name": "Dark Theme",
       "modes": [
         {
           "name": "dark",
           "variables": [
             {
               "variableId": "123",
               "value": "#000000"
             }
           ]
         }
       ]
     }
   }
   

API 文档

服务方法

• startServer(figmaToken: string, debug?: boolean, port?: number)
  • 初始化并启动 MCP 服务
  • 返回：Promise

工具模式

所有工具输入均使用 Zod 模式进行验证：

const CreateVariablesSchema = z.object({
  fileKey: z.string(),
  variables: z.array(z.object({
    name: z.string(),
    type: z.enum(['COLOR', 'FLOAT', 'STRING']),
    value: z.string(),
    scope: z.enum(['LOCAL', 'ALL_FRAMES'])
  }))
});

错误处理

该服务会提供详细的错误消息和适当的错误代码：

• 无效令牌：403，并附带具体错误消息
• 速率限制：429，并附带重置时间
• 验证错误：400，并附带字段级详情
• 服务端错误：500，并进行错误追踪

限制和已知问题

API 限制

1. 只读操作

   • 由于 Figma API 的限制，仅支持只读操作
   • 个人访问令牌仅支持读取操作，不支持写入
   • 无法通过个人令牌使用 REST API 修改变量、组件或样式
   • 写入操作需要开发 Figma 插件

2. 速率限制

   • 遵循 Figma API 的速率限制
   • 实施指数退避，以便更好地处理

3. 缓存管理

   • 默认 TTL 为 5 分钟
   • 最多缓存 500 条目
   • 可考虑实现缓存失效钩子

4. 身份验证

   • 仅支持个人访问令牌
   • 不支持团队级权限或协作编辑
   • 计划在未来实现 OAuth

5. 技术实现

   • 配置中需要使用绝对路径
   • 执行前必须编译 TypeScript 文件
   • 需要处理本地和全局模块解析

贡献

1. Fork 此仓库
2. 创建功能分支
3. 编写代码并添加测试
4. 提交拉取请求

请遵循我们的编码规范：

• TypeScript 严格模式
• ESLint 配置
• 使用 Jest 进行测试
• 完善的错误处理

许可证

MIT 许可证——详情请参阅 LICENSE 文件

故障排除

请参阅 TROUBLESHOOTING.md，获取完整的故障排除指南。

常见问题

1. JSON 连接错误

   • 在 Claude Desktop 配置中使用绝对路径
   • 确保服务已构建（npm run build）
   • 确认已设置所有环境变量

2. 身份验证问题

   • 确认你的 Figma 访问令牌有效
   • 检查令牌是否具有所需权限
   • 确保已在配置中正确设置令牌

3. 服务无法启动

   • 检查 Node.js 版本（需要 18.x+）
   • 确认构建文件存在（dist/index.js）
   • 检查 Claude Desktop 日志：
     • macOS：~/Library/Logs/Claude/mcp*.log
     • Windows：%APPDATA%\Claude\logs\mcp*.log

如需了解更详细的调试步骤和解决方案，请参阅故障排除指南。

支持

• GitHub Issues：报告 Bug
• 文档：Wiki
• Discord：加入我们的社区