Figma MCP Server (Python)

使用FastMCP实现的Python版Figma模型上下文协议（MCP）服务器。该服务器允许AI助手通过WebSocket连接读取数据并分析设计。

🎯 机会

• 📖 数据读取获取关于文档、节点、组件和样式的详细信息
• 🔍 搜索与分析按类型扫描节点，搜索文本内容
• 📤 导出以各种格式导出节点为图像
• 📋 注释查看文档中的注释
• 🧩 组件处理组件及其副本
• 🔗 原型设计获取关于反应和关系的信息

🚫 限制

出于安全考虑，此服务器不支持：

• 创建新元素
• 更改样式、颜色或文本（工具 set_*）
• 节点更改操作（移动、调整大小、删除、克隆）

📋 可用工具（15个）

🔗 连接

• join_channel - 加入通道以与Figma通信

📖 接收信息

• get_document_info - 获取当前Figma文档的信息
• get_selection - 获取当前选择的信息
• read_my_design - 获取分配的详细信息，包括所有节点的细节
• get_node_info - 根据ID获取特定节点的信息
• get_nodes_info - 获取多个节点的信息
• get_node_children - 获取所有子节点的ID，完全递归投资
• get_styles - 获取文档中的所有样式
• get_local_components - 获取所有本地组件

🧩 组件

• get_instance_overrides - 获取组件实例重新定义

🔍 搜索与扫描

• scan_text_nodes - 扫描指定节点内的文本节点
• scan_nodes_by_types - 扫描特定类型的节点（TEXT, RECTANGLE, FRAME）

📤 导出

• export_node_as_image - 将节点导出为图像（PNG, JPG, SVG, PDF）

📋 注释

• get_annotations - 获取节点或整个文档的注释

🔗 原型设计

• get_reactions - 获取节点的反应（交互连接）

🏗️ 架构

AI客户端（Cursor） ←→ MCP服务器 ←→ WebSocket服务器 ←→ Figma插件

1. MCP服务器 - 提供AI工具
2. WebSocket服务器 - 协调连接和通道
3. Figma插件 - 在Figma中执行命令

🚀 快速开始

1. 建立依赖

cd python-version
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或者 venv\Scripts\activate  # Windows
pip install -r requirements.txt

2. 启动WebSocket服务器

python websocket_proxy.py --port 3055 --debug

3. 在Figma中启动

1. 打开Figma桌面应用
2. 转到插件 → 开发 → 从清单导入插件...
3. 选择 src/cursor_mcp_plugin/manifest.json
4. 运行Cursor MCP插件
5. 连接到端口3055上的服务器
6. 记住频道ID（例如：abc1123xyz）

4. 配置Cursor中的MCP

在MCP Cursor设置（.cursor/mcp.json）中添加以下配置：

{
  "mcpServers": {
    "figma-mcp": {
      "command": "python",
      "args": ["-m", "src.figma_mcp.server", "--server", "localhost:3055"],
      "cwd": "/path/to/your/figma_mcp"
    }
  }
}

替代方法（使用虚拟环境）：

{
  "mcpServers": {
    "figma-mcp": {
      "command": "/path/to/your/figma_mcp/venv/bin/python",
      "args": ["/path/to/your/figma_mcp/src/figma_mcp/server.py", "--server", "localhost:3055"]
    }
  }
}

注意：将 /path/to/your/figma_mcp 替换为项目的实际路径。

5. 运行MCP服务器

python -m src.figma_mcp.server --server localhost:3055

6. 连接到频道

使用接收到的频道ID使用工具 join_channel：

{
  "tool": "join_channel",
  "arguments": {
    "channel": "abc123xyz"
  }
}

🛠️ 使用示例

获取文档信息

{
  "tool": "get_document_info",
  "arguments": {}
}

获取节点信息

{
  "tool": "get_node_info", 
  "arguments": {
    "node_id": "4472:98013"
  }
}

获取所有子节点

{
  "tool": "get_node_children",
  "arguments": {
    "node_id": "4472:98012"
  }
}

搜索文本节点

{
  "tool": "scan_text_nodes",
  "arguments": {
    "node_id": "4472:98012",
    "use_chunking": true,
    "chunk_size": 50
  }
}

导出为图像

{
  "tool": "export_node_as_image",
  "arguments": {
    "node_id": "4472:98013",
    "format": "PNG",
    "scale": 2.0
  }
}

🔧 配置

WebSocket服务器

• 端口：3055（默认）
• 主机：localhost
• 调试模式：--debug

MCP服务器

• 服务器URL：localhost:3055（默认）
• 协议：MCP 2024-11-05
• 传输方式：stdio

Cursor MCP设置

在项目根目录或家目录创建文件 .cursor/mcp.json：

{
  "$schema": "https://schema.cursor.com/mcp.json",
  "mcpServers": {
    "figma-mcp": {
      "command": "python",
      "args": ["-m", "src.figma_mcp.server", "--server", "localhost:3055"],
      "cwd": "/absolute/path/to/figma_mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/figma_mcp"
      }
    }
  }
}

主要参数：

• command：运行Python的命令
• args：启动MCP服务器的参数
• cwd：工作目录（项目的绝对路径）
• env：环境变量（可选）

📁 项目结构

python-version/
├── src/figma_mcp/
│   ├── __init__.py
│   ├── server.py          # 主要的MCP服务器
│   ├── websocket_client.py # WebSocket客户端
│   ├── types.py           # Pydantic类型
│   └── utils.py           # 工具
├── tests/                 # 测试（41个测试）
├── websocket_proxy.py     # WebSocket服务器
├── requirements.txt       # 依赖项
└── README.md             # 文档

🧪 测试

运行所有测试：

python -m pytest tests/ -v

连接测试：

python test_mcp.py

🔒 安全性

• 从Figma响应中过滤机密数据
• 使用Pydantic验证所有参数
• 处理错误和超时
• 输出到stderr用于调试

📦 依赖项

• fastmcp：2.4.0 - MCP服务器框架
• websockets：15.0.1 - WebSocket客户端/服务器
• pydantic：2.11.5 - 数据验证
• pytest：8.3.5 - 测试

🐛 调试

1. 连接问题：检查WebSocket服务器的状态
2. 超时：增加WebSocket客户端的超时时间
3. 频道错误：确保您使用了正确的频道ID。
4. 日志：查看stderr输出以获取详细信息

📝 许可证

MIT许可证

🤝 贡献

1. 分叉仓库
2. 为功能创建分支
3. 添加测试
4. 发送拉取请求