Figma MCP Server (Python)

Figma Model Context Protocol (MCP) server, реализованный на Python с использованием FastMCP. Этот сервер позволяет AI ассистентам взаимодействовать с Figma через 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 Client (Cursor) ←→ MCP Server ←→ WebSocket Server ←→ Figma Plugin

1. MCP Server - Предоставляет инструменты для AI

2. WebSocket Server - Координирует соединения и каналы

3. Figma Plugin - Выполняет команды в 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 Desktop

2. Перейдите в Plugins → Development → Import plugin from manifest...

3. Выберите `src/cursor_mcp_plugin/manifest.json`

4. Запустите плагин "Cursor MCP Plugin"

5. Подключитесь к серверу на порту 3055

6. Запомните Channel ID (например: `abc123xyz`)

4. Настройка MCP в Cursor

Добавьте следующую конфигурацию в настройки 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. Подключение к каналу

Используйте инструмент `join_channel` с полученным Channel ID:

{
  "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 Server

• Порт: 3055 (по умолчанию)
• Host: localhost
• Debug режим: `--debug`

MCP Server

• Server URL: localhost:3055 (по умолчанию)
• Протокол: MCP 2024-11-05
• Transport: stdio

Cursor MCP Settings

Создайте файл `.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. Таймауты: Увеличьте timeout в WebSocket клиенте

3. Ошибки каналов: Убедитесь, что используете правильный Channel ID

4. Логи: Смотрите вывод в stderr для детальной информации

📝 Лицензия

MIT License

🤝 Вклад

1. Форкните репозиторий

2. Создайте ветку для функции

3. Добавьте тесты

4. Отправьте pull request