Figma MCP 服务器

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

项目状态

当前进展

• ✅ 核心实现：已成功构建遵循模型上下文协议（MCP）的TypeScript服务器
• ✅ Claude桌面版集成：已测试并能在Claude Desktop上正常工作
• ✅ 读取操作：用于访问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 Access Token
FIGMA_ACCESS_TOKEN=your_figma_token

# Server Configuration
MCP_SERVER_PORT=3000

# Debug Configuration
DEBUG=figma-mcp:*

1. 对于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 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. 叉开仓库
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: 加入我们的社区