Figma MCP 服务器

一个模型上下文协议（MCP）服务器，通过 Claude 和其他 MCP 兼容客户端提供与 Figma API 的集成。目前支持对 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

配置

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

# Figma API 访问令牌
FIGMA_ACCESS_TOKEN=your_figma_token

# 服务器配置
MCP_SERVER_PORT=3000

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

对于 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);

可用工具

get-file

检索 Figma 文件详细信息

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

list-files

列出 Figma 项目中的文件

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

create-variables

创建设计系统变量

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

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 限制

只读操作
- 由于 Figma API 限制，仅限于只读操作
- 个人访问令牌仅支持读取操作，不支持写入
- 无法通过 REST API 使用个人令牌修改变量、组件或样式
- 写入操作需要 Figma 插件开发
速率限制
- 遵循 Figma API 速率限制
- 实施指数退避以更好地处理
缓存管理
- 默认 5 分钟 TTL
- 限制为 500 个条目
- 考虑实施缓存失效钩子
认证
- 仅支持个人访问令牌
- 不支持团队级权限或协作编辑
- 计划未来实施 OAuth
技术实现
- 配置中需要绝对路径
- 执行前必须编译 TypeScript 文件
- 需要处理本地和全局模块解析

贡献

Fork 仓库
创建一个功能分支
进行更改并附带测试
提交拉取请求

请遵循我们的编码标准：

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

许可证

MIT 许可证 - 详见 LICENSE 文件

故障排除

有关全面的故障排除指南，请参阅 TROUBLESHOOTING.md。

常见问题

JSON 连接错误
- 在 Claude 桌面配置中使用绝对路径
- 确保服务器已构建（npm run build）
- 验证所有环境变量已设置
认证问题
- 验证您的 Figma 访问令牌是否有效
- 检查令牌是否具有所需权限
- 确保令牌在配置中正确设置
服务器未启动
- 检查 Node.js 版本（需要 18.x+）
- 验证构建是否存在（dist/index.js）
- 检查 Claude 桌面日志：
  - macOS: ~/Library/Logs/Claude/mcp*.log
  - Windows: %APPDATA%\Claude\logs\mcp*.log

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

支持

GitHub Issues: 报告错误
文档: Wiki
Discord: 加入我们的社区