MCP 服务器

Figma MCP Server

通过模型上下文协议实现与 Figma 的无缝交互，使 LLM 应用程序能够访问、操作和跟踪 Figma 文件、组件和变量。

AI集成系统

访问服务器

Tools

get-file

Get details of a Figma file

list-files

List files in a Figma project

README

Figma MCP 服务器

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

项目状态

当前进度

✅ 核心实现: 成功构建了一个遵循模型上下文协议 (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（模型上下文协议）的基本理解

安装

npm install figma-mcp-server

配置

基于 .env.example 创建一个 .env 文件：

# Figma API 访问令牌
FIGMA_ACCESS_TOKEN=your_figma_token

# 服务器配置
MCP_SERVER_PORT=3000

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

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

可用工具

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<MCPServer>

工具模式

所有工具输入都使用 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 Desktop 配置中使用绝对路径
- 确保服务器已构建 (npm run build)
- 验证是否已设置所有环境变量
身份验证问题
- 验证您的 Figma 访问令牌是否有效
- 检查令牌是否具有所需的权限
- 确保令牌已在配置中正确设置
服务器未启动
- 检查 Node.js 版本（需要 18.x+）
- 验证构建是否存在 (dist/index.js)
- 检查 Claude Desktop 日志：
  - macOS: ~/Library/Logs/Claude/mcp*.log
  - Windows: %APPDATA%\Claude\logs\mcp*.log