figma-console-mcp: cho AI đọc và vẽ trực tiếp trong Figma — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về southleft/figma-console-mcp — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: figma-console-mcp: cho AI đọc, tạo, sửa thiết kế trong Figma — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
figma-console-mcp là một MCP server giúp trợ lý AI như Claude đọc và chỉnh sửa trực tiếp file Figma: lấy token, component, tạo khung giao diện, quản lý biến, kiểm tra trợ năng. Cài bằng một lệnh npx và một plugin nhập vào Figma Desktop, mất khoảng 10 phút theo README. Bạn cần Node.js 18+, Figma Desktop và một token cá nhân của Figma.
figma-console-mcp là một MCP server (cầu nối cho phép trợ lý AI dùng công cụ bên ngoài) dành cho Figma. Nó cho AI như Claude, Cursor, Windsurf… đọc dữ liệu thiết kế của bạn và ghi ngược lại vào Figma: tạo frame, tạo component, sửa biến màu, dựng bảng FigJam. Tác giả mô tả nó là "design system của bạn như một API".
Repo này hợp với designer, lập trình viên front-end và những người làm sản phẩm muốn AI hiểu đúng bộ token, variant, trạng thái của design system thay vì đoán mò. Dữ liệu AI nhận được là dữ liệu có cấu trúc, nên code AI sinh ra bám theo công nghệ và quy ước của chính nhóm bạn. Repo không ép một framework hay phong cách nào.
Điểm đáng giá nhất là nó đi được cả hai chiều (Figma sang code và code sang Figma), lại có các bước kiểm tra tất định như so khớp design với code, quét trợ năng, chấm điểm sức khỏe design system. Hiện repo có khoảng 3297 sao và 302 fork, giấy phép MIT, viết bằng TypeScript. Bạn có thể xem video ngắn bên dưới để thấy nó chạy trước khi cài.
southleft/figma-console-mcp
MCP server nối AI (Claude, Cursor…) với Figma để đọc design system, tạo frame, quản lý biến, quét trợ năng và so khớp design với code.
I.figma-console-mcp làm được gì
README liệt kê rất nhiều tính năng. Mình gom lại thành những nhóm bạn dễ dùng nhất:
- Đọc design system. Lấy biến (variables), component và style từ file Figma. Lợi ích: AI biết chính xác màu, khoảng cách, kiểu chữ bạn đang dùng.
- Tạo và sửa thiết kế. Tạo frame, component, layout ngay trong Figma, kể cả tạo cả component set từ một ma trận variant chỉ bằng một lệnh. Lợi ích: bạn mô tả bằng tiếng thường, AI dựng khung ban đầu.
- Quản lý biến (token). Tạo, cập nhật, đổi tên, xóa token. Lợi ích: thêm một chế độ mới như "High Contrast" vào bộ màu có sẵn không cần bấm từng ô.
- Đồng bộ token hai chiều. Xuất biến Figma ra DTCG JSON (cộng thêm 9 định dạng khác) và đẩy chỉnh sửa từ phía code ngược lại Figma. README nói nó thay thế được Style Dictionary và pipeline xuất của Tokens Studio.
- Trích design system từ codebase. Quét một codebase thật, rút ra token kèm nguồn gốc từng token, dựng gói design system có Storybook, rồi đưa token vào biến Figma (chỉ ở chế độ Local).
- Chụp màn hình để gỡ lỗi hình ảnh và theo dõi log console theo thời gian thực từ plugin Desktop Bridge.
- Lịch sử phiên bản. Liệt kê phiên bản, so sánh các bản chụp, tạo changelog dạng markdown.
- Quét trợ năng. 14 kiểm tra WCAG cho thiết kế, có phân loại mức tuân thủ và bảng điểm cho từng component, kèm quét code bằng axe-core.
- So khớp design với code. So sánh một component Figma với code của nó về hình ảnh, khoảng cách, kiểu chữ, token, API component và trợ năng. Có thể sinh luôn tài liệu component.
- Kiểm tra sức khỏe design system. Chấm điểm kiểu Lighthouse theo các mục như đặt tên, token, metadata component, trợ năng, tính nhất quán, độ phủ.
- FigJam và Slides. Tạo sticky, flowchart, bảng, khối code trên FigJam; dựng và quản lý bộ slide của Figma Slides.
- Cloud Write Relay. Cho phép các AI chạy trên web (Claude.ai, v0, Replit) thiết kế trong Figma qua cơ chế ghép cặp trên đám mây.
Bản mới nhất theo README (v1.46.0) còn thêm shader, auto layout/grid bằng một lệnh, màu OKLCH và Display P3, cùng các tùy chọn chữ như text wrap. Phiên bản trước đó (v1.45) có phần Motion để tạo hoạt ảnh cho layer.
II.Cần chuẩn bị gì
Theo README, có bốn cách kết nối, mỗi cách cần chuẩn bị khác nhau. Cách được khuyên dùng là NPX, và bài này tập trung vào cách đó.
Với NPX bạn cần:
- Node.js 18 trở lên. Kiểm tra bằng
node --version. File package.json của repo cũng yêu cầu Node từ 18.0.0. - Figma Desktop đã cài (chỉ dùng bản web là không đủ).
- Một MCP client, ví dụ Claude Code, Cursor, Windsurf, Claude Desktop.
- Personal access token của Figma (bắt đầu bằng
figd_). Cách tạo ở bước 1 bên dưới.
Bảng so sánh trong README cho thấy:
| Cách kết nối | Dùng khi nào | Tổng số tool |
|---|---|---|
| NPX hoặc Local Git | Tạo và sửa thiết kế, đầy đủ nhất | 130 |
| Cloud Mode | Dùng từ Claude.ai, v0, Replit, Lovable; không cần Node.js | 105 sau khi ghép cặp |
| Remote SSE | Chỉ xem dữ liệu, thử nhanh | Bộ tool chỉ đọc |
README không nêu yêu cầu GPU hay cấu hình máy. Phần giá cả hay hạn mức của MCP client bạn dùng cũng không được nói đến, bạn tự kiểm tra bên phía client.
III.Cài đặt từng bước
- Lấy token FigmaTạo personal access token trên Figma và chép lại chuỗi bắt đầu bằng figd_
- Thêm vào MCP clientChạy một lệnh (Claude Code) hoặc dán JSON vào file cấu hình
- Nhập plugin Desktop BridgeTrong Figma Desktop, nhập file manifest.json rồi chạy plugin
- Khởi động lại MCP clientĐể client nạp cấu hình mới
- Thử lệnh đầu tiênHỏi trạng thái Figma, rồi nhờ AI tạo một frame
A.Lấy token Figma
Vào trang trợ giúp của Figma, mục "Manage personal access tokens", rồi tạo token mới. Ô mô tả bạn điền Figma Console MCP. Phần quyền (scopes), README ghi: tất cả ở mức Read, riêng Comments là Read and write. Các mục gồm File content, File versions, Library content, Library assets, Comments, Current user, và Variables (chỉ dành cho gói Enterprise, không bắt buộc).
Sao chép token ngay vì Figma chỉ hiện một lần. Token có dạng figd_....
Token này cho phép truy cập file Figma của bạn. Đừng dán nó vào chat, ảnh chụp màn hình hay file công khai. Nếu lộ, hãy thu hồi và tạo token mới trong Figma.
B.Thêm server vào MCP client
Nếu bạn dùng Claude Code, chỉ cần một lệnh. Mở terminal (trên Windows là PowerShell hoặc Command Prompt), thay figd_YOUR_TOKEN_HERE bằng token của bạn rồi chạy:
claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latestLệnh này đăng ký một server tên figma-console, truyền token qua biến môi trường FIGMA_ACCESS_TOKEN, và tự tải bản mới nhất bằng npx.
README cũng có lệnh tương tự cho OpenAI Codex và Gemini CLI:
codex mcp add figma-console --env FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE --env ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latestgemini mcp add -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true figma-console npx -y figma-console-mcp@latestVới Codex, README dặn đặt startup_timeout_sec = 60 và tool_timeout_sec = 300 trong ~/.codex/config.toml vì mặc định (10 giây và 60 giây) quá ngắn.
Nếu bạn dùng Cursor, Windsurf hoặc Claude Desktop, hãy mở file cấu hình MCP của app và thêm đoạn sau:
{
"mcpServers": {
"figma-console": {
"command": "npx",
"args": ["-y", "figma-console-mcp@latest"],
"env": {
"FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
"ENABLE_MCP_APPS": "true"
}
}
}
}File cấu hình nằm ở đâu? README ghi:
- Claude Desktop trên Windows:
%APPDATA%\Claude\claude_desktop_config.json - Cursor trên Windows:
%USERPROFILE%\.cursor\mcp.json - Windsurf trên Windows:
%USERPROFILE%\.codeium\windsurf\mcp_config.json - Trên macOS, các file tương ứng là
~/Library/Application Support/Claude/claude_desktop_config.json,~/.cursor/mcp.jsonvà~/.codeium/windsurf/mcp_config.json.
Ký hiệu ~ là thư mục home của bạn. Nếu file chưa tồn tại, cứ tạo mới, app sẽ nhận khi khởi động lại. Chỗ người mới hay vấp là JSON thiếu dấu phẩy hoặc ngoặc, nên hãy kiểm tra kỹ cả file phải là JSON hợp lệ.
C.Nhập plugin Desktop Bridge vào Figma
Đây là bước nối AI với file Figma đang mở. Làm theo README:
- Mở Figma Desktop bình thường (không cần cờ đặc biệt nào) và mở một file.
- Vào Plugins → Development → Import plugin from manifest...
- Chọn file
~/.figma-console-mcp/plugin/manifest.json. Đường dẫn này do MCP server tự tạo. Để biết chính xác đường dẫn trên máy bạn, chạy:
npx figma-console-mcp --print-path- Chạy plugin trong file Figma. Nó tự quét các cổng 9223–9232 và nối với MCP server đang chạy.
Lưu ý: thư mục .figma-console-mcp bắt đầu bằng dấu chấm nên macOS ẩn nó. Trong hộp thoại chọn file, bấm ⌘⇧G rồi dán đường dẫn, hoặc bấm ⌘⇧. để hiện file ẩn. Trên Windows thư mục hiện bình thường.
Một điểm nữa: Figma lưu đệm file plugin. Server làm mới file mỗi lần khởi động, nhưng Figma vẫn dùng bản đệm cho đến khi bạn nhập lại manifest. README nói chỉ bắt buộc nhập lại khi ghi chú phát hành yêu cầu. Khi cần, vào Plugins → Manage plugins và nhập lại đúng file manifest ở đường dẫn cũ.
D.Khởi động lại MCP client
Đóng hẳn app (Claude Desktop, Cursor…) rồi mở lại để nó nạp cấu hình mới. Với Claude Code, mở phiên mới.
IV.Kiểm tra đã chạy được chưa
Trong MCP client, gõ câu sau:
Check Figma statusKết quả mong đợi theo README: hiện trạng thái kết nối, với kênh WebSocket đang hoạt động.
Tiếp theo thử quyền ghi:
Create a simple frame with a blue backgroundNếu một frame nền xanh xuất hiện trong file Figma đang mở, nghĩa là bạn đã có quyền ghi và mọi thứ nối đúng. Nếu chỉ thấy trạng thái nhưng không tạo được frame, hãy xem phần lỗi thường gặp bên dưới.
V.Dùng vào việc thật
README chủ yếu cho ví dụ câu lệnh ngắn bằng tiếng Anh. Các tình huống dưới đây bám theo khả năng được liệt kê trong tư liệu. Câu lệnh mẫu là gợi ý của mình, bạn chỉnh theo file của bạn.
A.Designer dựng nhanh một component
Bạn là designer đang làm bộ UI cho một app. Thay vì kéo thả từng lớp, bạn mô tả cho AI. Ví dụ README đưa ra:
Create a card component with a header image, title, description, and action buttonAI tạo component trực tiếp trong file đang mở. Bạn mở Figma kiểm tra, chỉnh lại chi tiết cho đúng ý. README còn nói có thể tạo cả component set từ một ma trận variant trong một lần gọi, hợp khi bạn có nhiều kích cỡ và trạng thái nút.
Cho AI đọc đúng token và variant của bạn, code nó sinh ra sẽ bám theo design system thay vì tự bịa.
Ông T
B.Thêm chế độ màu cho bộ token có sẵn
Bạn quản lý token màu và cần thêm chế độ tương phản cao. Bạn nhờ:
Add a "High Contrast" mode to my existing token collectionAI dùng các tool quản lý biến để thêm mode vào collection. Bạn kiểm tra trong bảng Variables của Figma. README cho biết Cloud Mode dùng Plugin API nên làm việc với biến được trên mọi gói, không cần Enterprise.
C.Lập trình viên so khớp component với code
Bạn là dev front-end và muốn biết nút trong code có lệch so với bản thiết kế không. README nói repo có công cụ so sánh tất định giữa một component Figma và code của nó, về hình ảnh, khoảng cách, kiểu chữ, token, API component và trợ năng. Bạn chọn component trong Figma, rồi nhờ AI chạy so khớp với file code tương ứng. Kết quả là danh sách điểm khác nhau cụ thể để sửa, thay vì cảm tính "trông hơi lệch".
D.Trưởng nhóm kiểm tra sức khỏe design system
Bạn phụ trách thư viện component chung và muốn biết nó còn lộn xộn ở đâu. Bạn nhờ AI chạy audit sức khỏe design system. README mô tả đây là bản chấm điểm kiểu Lighthouse theo các mục đặt tên, token, metadata component, trợ năng, tính nhất quán và độ phủ, kèm gợi ý tự sửa cho từng phát hiện. Bạn có một danh sách việc cần làm có thứ tự, hữu ích khi họp với nhóm.
VI.Lỗi hay gặp và cách xử lý
1. AI báo không thấy server hoặc không có tool Figma. Thường do chưa khởi động lại client sau khi sửa cấu hình, hoặc JSON bị sai. Mở file cấu hình, kiểm tra dấu phẩy, ngoặc, rồi khởi động lại hẳn app.
2. Hỏi trạng thái được nhưng không tạo được gì trong Figma. Plugin Desktop Bridge có thể chưa chạy trong file đang mở. Mở lại plugin trong Plugins → Development, đảm bảo nó đang chạy cùng lúc với MCP client. Plugin quét các cổng 9223–9232, nên hãy chắc không có chương trình nào khác chiếm các cổng này.
3. Plugin cũ, thiếu tính năng mới. Figma dùng bản plugin đệm. Nếu ghi chú phát hành nói cần nhập lại, hãy nhập lại file manifest ở đường dẫn cũ. README nói plugin hiện banner cập nhật khi server có bản plugin mới hơn.
4. Không tìm thấy thư mục .figma-console-mcp khi nhập plugin.
Trên macOS thư mục bị ẩn: bấm ⌘⇧G rồi dán đường dẫn, hoặc ⌘⇧. để hiện file ẩn. Chạy npx figma-console-mcp --print-path để lấy đường dẫn chính xác.
5. Codex báo hết thời gian khi khởi động hoặc gọi tool.
Đặt startup_timeout_sec = 60 và tool_timeout_sec = 300 trong ~/.codex/config.toml như README hướng dẫn.
VII.Có nên dùng không
Điểm mạnh. Phạm vi rộng: đọc, ghi, đồng bộ token, quét trợ năng, so khớp với code, audit design system, tất cả trong một công cụ MIT mã nguồn mở. Kết nối được với nhiều client (Claude Code, Cursor, Windsurf, Claude Desktop, Codex, Gemini CLI). Repo còn được cập nhật trong 3 tháng gần đây, và có tài liệu riêng cùng file CHANGELOG.
Giới hạn. Cách đầy đủ nhất cần Node.js, Figma Desktop và nhập plugin thủ công, nên không hẳn là cài một chạm. Remote SSE chỉ đọc. Cloud Mode ít tool hơn (105 so với 130) và không có theo dõi thời gian thực. Số lượng tool lớn có thể làm người mới choáng, nên hãy bắt đầu bằng vài câu lệnh đơn giản. Vì AI ghi trực tiếp vào file thật, bạn nên làm trên bản sao hoặc file thử trước khi chạy trên file chính.
Khi nào chọn cách khác. Nếu bạn chỉ cần xem dữ liệu Figma và không muốn cài gì, thử Remote SSE hoặc Cloud Mode theo README. Nếu bạn không dùng AI trong quy trình thiết kế thì repo này không đem lại gì thêm.
Câu hỏi thường gặp
figma-console-mcp có miễn phí không?
Repo dùng giấy phép MIT và bạn cài được bằng npx. README không nói về phí của chính repo. Chi phí của MCP client hoặc gói Figma bạn đang dùng thì README không đề cập, bạn cần tự kiểm tra.
Có cần GPU hay máy cấu hình mạnh không?
README không nêu yêu cầu GPU hay cấu hình phần cứng. Điều kiện được ghi rõ là Node.js 18 trở lên, Figma Desktop và một MCP client.
Chạy được trên Windows không?
README có ghi đường dẫn file cấu hình cho cả macOS và Windows, ví dụ `%APPDATA%\Claude\claude_desktop_config.json` cho Claude Desktop. Phần nhập plugin cũng nói rõ trên Windows thư mục plugin hiện bình thường.
Cần bản Figma nào? Dùng Figma trên web được không?
Cách NPX cần Figma Desktop vì plugin Desktop Bridge chạy trong đó. Cloud Mode cũng cần Figma Desktop có plugin, nhưng phía AI thì dùng được từ web như Claude.ai, v0, Replit, Lovable mà không cần Node.js.
Token Figma của tôi có an toàn không?
Token được đặt trong biến môi trường `FIGMA_ACCESS_TOKEN` của cấu hình MCP trên máy bạn. README không có phần phân tích bảo mật chi tiết trong đoạn được cung cấp, nhưng repo có file SECURITY.md để bạn đọc thêm. Hãy giữ token bí mật và thu hồi nếu bị lộ.
Có cần gói Figma Enterprise không?
Không bắt buộc. Scope Variables của token chỉ dành cho Enterprise và là tùy chọn. README nói Cloud Mode dùng Plugin API nên làm việc với biến được trên mọi gói.
Khác gì Style Dictionary hay Tokens Studio?
README nói tính năng đồng bộ token hai chiều của repo thay thế pipeline xuất của Style Dictionary và Tokens Studio. Nó xuất biến Figma ra DTCG JSON cùng 9 định dạng khác và đẩy chỉnh sửa từ code ngược lại Figma. README trong phần được cung cấp chưa có so sánh chi tiết hơn.


