Figma MCP Server

一个通过Claude和其他兼容MCP的客户端与Figma API集成的模型上下文协议（MCP）服务器。当前支持对Figma文件和项目的只读访问，并且服务器架构能够支持更高级的设计令牌和主题管理功能（取决于Figma API增强或插件开发）。

项目状态

当前进度

• ✅ 核心实现：成功构建了一个遵循模型上下文协议（MCP）的TypeScript服务器
• ✅ Claude桌面集成：已测试并可在Claude桌面中正常工作
• ✅ 读操作：用于访问Figma文件的get-file和list-files工具正在运行
• ✅ 服务器架构：实现了缓存系统、错误处理和统计监控
• ✅ 传输协议：支持stdio和SSE传输机制

潜在全功能

该服务器设计了代码以支持这些功能（目前受限于API限制）：

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

随着Figma插件开发或扩展API访问权限，这些功能可以完全启用。

功能

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

预备条件

• Node.js 18.x或更高版本
• 具有适当权限的Figma访问令牌
• 对MCP（模型上下文协议）的基本理解

安装

npm install figma-mcp-server

配置

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

# Figma API访问令牌
FIGMA_ACCESS_TOKEN=your_figma_token

# 服务器配置
MCP_SERVER_PORT=3000

# 调试配置
DEBUG=figma-mcp:*

2. 对于Claude桌面集成：

可以在你的Claude桌面配置文件中配置服务器：

• 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桌面

使用

基本使用

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项目中的文件

   {
     1. "name": "list-files",
     2. "arguments": {
     3.   "projectId": "your_project_id"
     4. }
     5. }
     6. ```
     7.
     8. 3. **create-variables**
     9.    - 创建设计系统变量
     10.   ```javascript
     11.   {
     12.     "name": "create-variables",
     13.     "arguments": {
     14.       "fileKey": "your_file_key",
     15.       "variables": [
     16.         {
     17.           "name": "primary-color",
     18.           "type": "COLOR",
     19.           "value": "#0066FF"
     20.         }
     21.       ]
     22.     }
     23.   }
     24.   ```
     25.
     26. 4. **create-theme**
     27.    - 创建和配置主题
     28.   ```javascript
     29.   {
     30.     "name": "create-theme",
     31.     "arguments": {
     32.       "fileKey": "your_file_key",
     33.       "name": "Dark Theme",
     34.       "modes": [
     35.         {
     36.           "name": "dark",
     37.           "variables": [
     38.             {
     39.               "variableId": "123",
     40.               "value": "#000000"
     41.             }
     42.           ]
     43.         }
     44.       ]
     45.     }
     46.   }
     47.   ```
     48.
     49. ## API文档
     50.
     51. ### 服务器方法
     52.
     53. - `startServer(figmaToken: string, debug?: boolean, port?: number)`
     54.   - 初始化并启动MCP服务器
     55.   - 返回值：Promise<MCPServer>
     56.
     57. ### 工具模式
     58.
     59. 所有工具输入都使用Zod模式进行验证：
     60.
     61. ```typescript
     62. const CreateVariablesSchema = z.object({
     63.   fileKey: z.string(),
     64.   variables: z.array(z.object({
     65.     name: z.string(),
     66.     type: z.enum(['COLOR', 'FLOAT', 'STRING']),
     67.     value: z.string(),
     68.     scope: z.enum(['LOCAL', 'ALL_FRAMES'])
     69.   }))
     70. });
     71. ```
     72.
     73. ## 错误处理
     74.
     75. 服务器提供详细的错误消息和适当的错误代码：
     76.
     77. - 无效令牌：403，附带特定错误消息
     78. - 速率限制：429，附带重置时间
     79. - 验证错误：400，附带字段特定细节
     80. - 服务器错误：500，附带错误跟踪
     81.
     82. ## 限制及已知问题
     83.
     84. ### API限制
     85.
     86. 1. **只读操作**
     87.    - 由于Figma API限制，仅限于只读操作
     88.    - 个人访问令牌仅支持读操作，不支持写操作
     89.    - 无法通过REST API和个人令牌修改变量、组件或样式
     90.    - 写操作需要Figma插件开发
     91.
     92. 2. **速率限制**
     93.    - 遵循Figma API速率限制
     94.    - 实现指数退避以更好地处理
     95.
     96. 3. **缓存管理**
     97.    - 默认5分钟TTL
     98.    - 限制为500条目
     99.    - 考虑实现缓存失效钩子
     100.
     101. 4. **认证**
     102.    - 仅支持个人访问令牌
     103.    - 不支持团队级权限或协作编辑
     104.    - 计划在未来实现OAuth
     105.
     106. 5. **技术实现**
     107.    - 配置中需要绝对路径
     108.    - 执行前必须编译TypeScript文件
     109.    - 必须处理本地和全局模块解析
     110.
     111. ## 贡献
     112.
     113. 1. 分叉仓库
     114. 2. 创建功能分支
     115. 3. 编写带有测试的更改
     116. 4. 提交拉取请求
     117.
     118. 请遵守我们的编码标准：
     119. - TypeScript严格模式
     120. - ESLint配置
     121. - 使用Jest进行测试
     122. - 全面的错误处理
     123.
     124. ## 许可
     125.
     126. MIT许可 - 查看LICENSE文件获取详细信息
     127.
     128. ## 故障排除
     129.
     130. 查看[TROUBLESHOOTING.md](examples/TROUBLESHOOTING.md)以获取全面的故障排除指南。
     131.
     132. ### 常见问题
     133.
     134. 1. **JSON连接错误**
     135.    - 在Claude桌面配置中使用绝对路径
     136.    - 确保服务器已构建（`npm run build`）
     137.    - 验证所有环境变量已设置
     138.
     139. 2. **认证问题**
     140.    - 验证您的Figma访问令牌有效
     141.    - 检查令牌具有所需权限
     142.    - 确保配置中正确设置了令牌
     143.
     144. 3. **服务器未启动**
     145.    - 检查Node.js版本（需18.x+）
     146.    - 验证构建存在（`dist/index.js`）
     147.    - 检查Claude桌面日志：
     148.      - macOS: `~/Library/Logs/Claude/mcp*.log`
     149.      - Windows: `%APPDATA%\Claude\logs\mcp*.log`
     150.
     151. 更多详细的调试步骤和解决方案，请参阅故障排除指南。
     152.
     153. ## 支持
     154.
     155. - GitHub Issues: [报告错误](https://github.com/your-repo/issues)
     156. - 文档: [Wiki](https://github.com/your-repo/wiki)
     157. - Discord: [加入我们的社区](https://discord.gg/your-server)