AI导哈

Figma MCP 服务器

一个遵循模型上下文协议（MCP）的服务器，提供与Figma API的集成，支持文件读取和设计系统管理功能。

  • by TimHolden
  • TypeScript
  • 本地部署
  • 149 星标
  • 更新于
在 GitHub 查看 TimHolden/figma-mcp-server

使用说明

Figma MCP服务器

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

项目状态

进展

  • ✅ 核心实施：已按照模型上下文协议（MCP）成功构建TypeScript服务器
  • ✅ Claude桌面集成：使用Claude Desktop进行测试并正常工作
  • ✅ 读取操作：工作 get-file 和 list-files Figma文件访问工具
  • ✅ 服务器架构：已实施缓存系统、错误处理和统计监控
  • ✅ 传输协议：支持stdio和SSE传输机制

潜在的完整功能

服务器的设计代码支持以下功能（目前受API限制）：

  • 变量管理：创建、读取、更新和删除设计标记（变量）
  • 参考资料处理：创建和验证令牌之间的关系
  • 主题管理：创建具有多种模式的主题（例如，亮/暗）
  • 相关性分析：检测并防止循环引用
  • 批量操作：对变量和主题执行批量操作

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

特性

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

先决条件

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

安装

npm install figma-mcp-server

配置

  1. 创建一个 .env 文件基于 .env.example:
# Figma API Access Token
FIGMA_ACCESS_TOKEN=your_figma_token

# Server Configuration
MCP_SERVER_PORT=3000

# Debug Configuration
DEBUG=figma-mcp:*
  1. 对于Claude Desktop集成：

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

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %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. 获取文件

    • 检索Figma文件详细信息
    {
  "name": "get-file",
  "arguments": {
    "fileKey": "your_file_key"
  }
}

  2. 列出文件

    • 列出Figma项目中的文件
    {
  "name": "list-files",
  "arguments": {
    "projectId": "your_project_id"
  }
}

  3. 创建变量

    • 创建设计系统变量
    {
  "name": "create-variables",
  "arguments": {
    "fileKey": "your_file_key",
    "variables": [
      {
        "name": "primary-color",
        "type": "COLOR",
        "value": "#0066FF"
      }
    ]
  }
}

  4. 创建主题

    • 创建和配置主题
    {
  "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. 缓存管理

    • 默认5分钟TTL
    • 仅限500个条目
    • 考虑实现缓存失效挂钩

  4. 认证

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

  5. 技术实现

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

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 通过测试进行更改
  4. 提交拉取请求

请遵循我们的编码标准：

  • TypeScript严格模式
  • ESLint配置
  • Jest用于测试
  • 全面的错误处理

许可证

MIT许可证-有关详细信息，请参阅许可证文件

故障排除

看 故障排除.md 获取全面的故障排除指南。

常见问题

  1. JSON连接错误

    • 在Claude Desktop配置中使用绝对路径
    • 确保服务器已构建(npm run build)
    • 验证是否已设置所有环境变量

  2. 身份验证问题

    • 验证您的Figma访问令牌是否有效
    • 检查令牌是否具有所需权限
    • 确保在配置中正确设置了令牌

  3. 服务器未启动

    • 检查Node.js版本（需要18.x+）
    • 验证构建是否存在(dist/index.js)
    • 检查克劳德桌面日志：
      • macOS： ~/Library/Logs/Claude/mcp*.log
      • 窗户： %APPDATA%\Claude\logs\mcp*.log

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

支持

相关 MCP