remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrations

Provides integration with Figma's API for read-only access to Figma files and projects, with architecture supporting design token and theme management features

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 Access Token
FIGMA_ACCESS_TOKEN=your_figma_token

# Server Configuration
MCP_SERVER_PORT=3000

# Debug Configuration
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);

可用工具

获取文件
- 检索 Figma 文件详细信息 GXP5
列出文件
- 列出 Figma 项目中的文件 GXP6
创建变量
- 创建设计系统变量 GXP7
创建主题
- 创建和配置主题 GXP8

API 文档

服务器方法

startServer(figmaToken: string, debug?: boolean, port?: number)
- 初始化并启动 MCP 服务器
- 回报：承诺

工具模式

所有工具输入均使用 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 文件
- 需要处理本地和全局模块解析

贡献

分叉存储库
创建功能分支
通过测试进行更改
提交拉取请求

请遵循我们的编码标准：

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

执照

MIT 许可证 - 详情请参阅许可证文件

故障排除

请参阅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

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

支持

GitHub 问题：报告错误
文档： Wiki
Discord：加入我们的社区

You must be authenticated.

A

security – no known vulnerabilities

F

license - not found

A

quality - confirmed to work

Tools

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

Related Resources

Reddit Discussion about this server

Figma MCP Server