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（模型上下文协议）的基本了解

安装

配置

1. 根据.env.example创建.env文件：

2. 对于 Claude Desktop 集成：

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

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows： %APPDATA%\Claude\claude_desktop_config.json

重要提示：

• 使用绝对路径，而不是相对路径

• 在 Windows 上，在路径中使用双反斜杠 (\\)

• 更改配置后重新启动 Claude Desktop

用法

基本用法

可用工具

1. 获取文件

   • 检索 Figma 文件详细信息 GXP5

2. 列出文件

   • 列出 Figma 项目中的文件 GXP6

3. 创建变量

   • 创建设计系统变量 GXP7

4. 创建主题

   • 创建和配置主题 GXP8

API 文档

服务器方法

• startServer(figmaToken: string, debug?: boolean, port?: number)

  • 初始化并启动 MCP 服务器

  • 回报：承诺

工具模式

所有工具输入均使用 Zod 模式进行验证：

错误处理

服务器提供详细的错误消息和正确的错误代码：

• 无效令牌：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 许可证 - 详情请参阅许可证文件

故障排除

请参阅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 问题：报告错误

• 文档： Wiki

• Discord：加入我们的社区