Skip to main content
Glama
enesjakozh
TimHolden

Figma MCP Server

by TimHolden
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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 访问，这些功能可以完全启用。

Related MCP server: Figma MCP Server

特征

  • 🔑 使用 Figma API 进行安全身份验证

  • 📁 文件操作（读取、列表）

  • 🎨 设计系统管理

    • 变量创建和管理

    • 主题创建和配置

    • 参考处理和验证

  • 🚀 性能优化

    • LRU缓存

    • 速率限制处理

    • 连接池

  • 📊 全面监控

    • 健康检查

    • 使用情况统计

    • 错误追踪

先决条件

  • Node.js 18.x 或更高版本

  • 具有适当权限的 Figma 访问令牌

  • 对 MCP（模型上下文协议）的基本了解

安装

npm install figma-mcp-server

配置

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

# 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

  • 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);

可用工具

  1. 获取文件

    • 检索 Figma 文件详细信息 GXP5

  2. 列出文件

    • 列出 Figma 项目中的文件 GXP6

  3. 创建变量

    • 创建设计系统变量 GXP7

  4. 创建主题

    • 创建和配置主题 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 限制

  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

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

支持

Available Tools

2 tools
get-fileA

Get details of a Figma file

ParametersJSON Schema
NameRequiredDescriptionDefault
fileKeyYesThe Figma file key

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden but only says 'get details'. No disclosure of what details include, authentication needs, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with verb and resource, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool, description is minimally complete but lacks specificity on what 'details' are returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter documented. Description adds no extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action ('Get') and resource ('details of a Figma file'). It distinguishes from sibling 'list-files' which lists files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. Usage is implied but not clarified.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-filesB

List files in a Figma project

ParametersJSON Schema
NameRequiredDescriptionDefault
projectIdYesThe Figma project ID

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, and description lacks behavioral context. Does not inform about pagination, result format, or any constraints. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy. However, it might be too minimal; a little more detail would improve without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers basic purpose but lacks guidance on response format, limitations, or differentiation from sibling. Adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameter is fully described in schema. Description does not add additional meaning or context (e.g., format of ID, where to find it). So baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states action (list) and resource (files in a Figma project). Distinguishes from sibling tool get-file which likely retrieves a single file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines provided; agent must infer from context alone. Does not mention when to use list versus get or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.1
    • First observedget-file
    • First observedlist-files
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

B3.4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are clearly distinct: one retrieves details of a specific file, the other lists files in a project. There is no overlap or ambiguity.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (get-file, list-files) using snake_case, making them predictable and readable.

Tool Count3/5

With only 2 tools, the server feels very thin for a full Figma integration. While the count is borderline, it is still usable for basic file listing and retrieval.

Completeness2/5

The server lacks critical operations such as creating, updating, or deleting files, and does not cover other common Figma resources like components or styles. This is a significant gap for expected Figma workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches