# figma-console-mcp: cho AI đọc và vẽ trong Figma — hướng dẫn cài đặt và dùng

> figma-console-mcp là một MCP server giúp trợ lý AI như Claude đọc, tạo và sửa thiết kế trong Figma, đồng thời kiểm tra design system và khả năng truy cập. Bạn cài bằng một lệnh npx, tạo token Figma, rồi nhập một plugin vào Figma Desktop. Với người mới thì cài ở mức trung bình, mất khoảng 10 phút theo README.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-18 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/figma-console-mcp-ket-noi-ai-voi-figma-doc-ve-kiem-tra-design-system

figma-console-mcp là một MCP server (một "cổng nối" để trợ lý AI dùng được công cụ bên ngoài) dành cho Figma. Khi cài xong, bạn có thể nhờ AI như Claude đọc dữ liệu thiết kế, tạo khung và component, sửa biến màu, chụp màn hình và kiểm tra chất lượng design system, ngay bằng câu chat thường.

Repo này hợp với nhà thiết kế UI, lập trình viên làm giao diện và những ai quản lý design system. Cũng hợp với chủ sản phẩm muốn nhờ AI dựng nhanh bản nháp trong Figma. Điểm đáng giá nhất là AI nhận dữ liệu có cấu trúc (token, biến thể, trạng thái) thay vì đoán từ ảnh chụp, nên mã sinh ra bám theo đúng quy ước của đội bạn. Hiện repo có khoảng 3293 sao và 301 fork, giấy phép MIT.

Bạn xem video ngắn bên dưới để thấy nó chạy thực tế, rồi quay lại đây làm theo từng bước.

```repo
- repo | southleft/figma-console-mcp
- kind | MCP server
- desc | MCP server nối trợ lý AI (Claude, Cursor…) với Figma để đọc design system, tạo khung và component, quản lý biến và kiểm tra chuẩn truy cập.
- stars | 3.3k
- lang | TypeScript
- license | MIT
```

```video
- youtube | https://youtube.com/shorts/5uVdALERxuQ
- facebook | https://www.facebook.com/reel/1449198444024879
- title | Video giới thiệu figma-console-mcp
```

## figma-console-mcp làm được gì

Theo README, repo đi theo hướng "design system như một API". Mình gom các tính năng chính theo lợi ích:

- **Đọc design system:** lấy biến, component và style từ file Figma. Bạn khỏi phải mở từng thứ ra chép tay.
- **Tạo thiết kế trực tiếp:** AI tạo frame, component, layout ngay trong Figma. Có cả việc tạo cả bộ component set từ một ma trận biến thể trong một lệnh.
- **Quản lý biến (design token):** tạo, sửa, đổi tên, xoá token. Hữu ích khi bạn cần thêm một chế độ màu mới.
- **Đồng bộ token hai chiều:** xuất biến Figma ra JSON chuẩn DTCG cùng 9 định dạng khác, rồi đẩy chỉnh sửa từ phía code ngược lại Figma. README nói nó thay được quy trình xuất của Style Dictionary và Tokens Studio.
- **Trích design system từ codebase:** quét một codebase đang chạy, rút các kiểu giao diện thực tế thành token, dựng gói design system kèm Storybook. Tính năng này chỉ có ở chế độ chạy trên máy (NPX / Local Git).
- **Gỡ lỗi bằng hình ảnh:** chụp màn hình để AI có ngữ cảnh. Ngoài ra có theo dõi log theo thời gian thực từ plugin.
- **Lịch sử phiên bản:** liệt kê phiên bản, so sánh bản chụp, tạo changelog dạng markdown.
- **FigJam và Slides:** tạo sticky, flowchart, bảng, khối code trên bảng FigJam, và dựng bộ slide trong Figma Slides.
- **Kiểm tra truy cập (accessibility):** 14 phép kiểm tra WCAG cho thiết kế, kèm quét mã bằng axe-core.
- **So khớp thiết kế và code:** so sánh một component Figma với bản code về hình ảnh, khoảng cách, chữ, token, API component và truy cập. Có thể sinh tài liệu component.
- **Chấm điểm sức khoẻ design system:** kiểu Lighthouse, xét đặt tên, token, metadata component, truy cập, tính nhất quán và độ phủ.
- **Cloud Write Relay:** cho phép các AI chạy trên web (Claude.ai, v0, Replit, Lovable) thiết kế trong Figma qua ghép nối đám mây.

README còn nêu bản mới có thêm shader, auto layout/grid, màu OKLCH và P3, cùng chuyển động (animation). Mình không đi sâu phần này vì bài tập trung vào cài đặt và dùng cơ bản.

## Cần chuẩn bị gì

Cách cài khuyến nghị của README là NPX. Bạn cần:

- **Node.js 18 trở lên.** Kiểm tra bằng `node --version`. package.json cũng yêu cầu Node từ 18.0.0.
- **Figma Desktop**, không chỉ bản web. Plugin cầu nối chạy trong ứng dụng desktop.
- **Một MCP client**: Claude Code, Cursor, Windsurf, Claude Desktop… README cũng có hướng dẫn cho OpenAI Codex, Gemini CLI và Google Antigravity.
- **Figma personal access token** (bắt đầu bằng `figd_`).

Còn hai đường khác, tuỳ nhu cầu:

- **Cloud Mode** (Claude.ai, v0, Replit, Lovable): không cần Node.js, nhưng vẫn cần token và Figma Desktop có plugin.
- **Remote SSE**: chỉ đọc dữ liệu, cài nhanh nhất (khoảng 2 phút theo README), không tạo hay sửa được thiết kế.

README nêu số công cụ: khoảng 130 công cụ với NPX / Local Git, 105 công cụ với Cloud Mode sau khi ghép nối. Remote SSE chỉ có nhóm công cụ chỉ đọc. Phần README mình có bị cắt giữa chừng, nên các mục như giá hay giới hạn dùng đám mây mình không bàn tới.

## Cài đặt từng bước

Mình hướng dẫn đường NPX, vì đây là đường đầy đủ nhất.

```steps
- Tạo token Figma | Tạo personal access token và chọn đúng quyền đọc
- Thêm vào MCP client | Chạy một lệnh (hoặc sửa file JSON) để khai báo server
- Nhập plugin vào Figma | Import manifest của Desktop Bridge rồi chạy plugin
- Khởi động lại client | Để client nạp cấu hình mới
- Thử lệnh đầu tiên | Hỏi trạng thái Figma, rồi tạo một frame thử
```

### Tạo token Figma

Vào trang trợ giúp của Figma, mục "Manage personal access tokens" và tạo token mới. Mô tả đặt là `Figma Console MCP`. README gợi ý các quyền, đều ở mức đọc trừ khi ghi chú khác:

- File content
- File versions
- Library content
- Library assets
- Comments (đọc và ghi)
- Current user
- Variables (chỉ dành cho gói Enterprise, không bắt buộc)

**Copy token ngay**, vì Figma chỉ hiện một lần. Token bắt đầu bằng `figd_`.

```note
Token Figma giống mật khẩu. Đừng dán vào chat, ảnh chụp màn hình hay file đưa lên GitHub. Chỉ đặt nó trong cấu hình của MCP client trên máy bạn. Nếu lỡ lộ, hãy thu hồi token trong Figma rồi tạo cái mới.
```

### Thêm server vào MCP client

Mở terminal (Terminal trên macOS, PowerShell hoặc Windows Terminal trên Windows). Nếu bạn dùng **Claude Code**, chạy lệnh dưới đây và thay `figd_YOUR_TOKEN_HERE` bằng token thật:

```bash
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@latest
```

Lệnh này đăng ký server tên `figma-console` ở phạm vi người dùng, truyền token qua biến `FIGMA_ACCESS_TOKEN` và chạy gói `figma-console-mcp` bằng npx. Bạn không phải cài gói trước.

Với **OpenAI Codex** (CLI):

```bash
codex mcp add figma-console --env FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE --env ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latest
```

README dặn thêm `startup_timeout_sec = 60` và `tool_timeout_sec = 300` cho server này trong `~/.codex/config.toml`, vì mặc định của Codex (10 giây / 60 giây) quá ngắn.

Với **Gemini CLI**:

```bash
gemini mcp add -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true figma-console npx -y figma-console-mcp@latest
```

Với **Cursor, Windsurf, Claude Desktop**, bạn thêm đoạn JSON này vào file cấu hình MCP của app:

```json
{
  "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, theo README:

- **Claude Desktop:** `%APPDATA%\Claude\claude_desktop_config.json` (Windows), `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS).
- **Cursor:** `%USERPROFILE%\.cursor\mcp.json` (Windows), `~/.cursor/mcp.json` (macOS).
- **Windsurf:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows), `~/.codeium/windsurf/mcp_config.json` (macOS).

Ký hiệu `~` là thư mục người dùng của bạn. Nếu file chưa có thì tự tạo. 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ỹ toàn file. Nếu có sẵn mục `mcpServers`, hãy thêm `figma-console` vào trong đó chứ đừng tạo khối thứ hai.

### Nhập plugin Desktop Bridge vào Figma

Đây là cầu nối giữa server và Figma, và bước này hay bị bỏ sót.

1. Mở Figma Desktop bình thường (không cần cờ đặc biệt) và mở một file.
2. Vào **Plugins → Development → Import plugin from manifest...**
3. Chọn file `~/.figma-console-mcp/plugin/manifest.json`. Server tự tạo đường dẫn cố định này khi chạy.
4. Chạy plugin trong file Figma. Plugin quét các cổng 9223–9232 và tự nối với server đang chạy.

Nếu không nhớ đường dẫn chính xác trên máy, in nó ra bằng:

```bash
npx figma-console-mcp --print-path
```

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, nhấn **⌘⇧G** rồi dán đường dẫn, hoặc **⌘⇧.** để hiện file ẩn. Trên Windows thư mục hiện bình thường.

Về sau, khi nâng cấp server, Figma vẫn dùng bản plugin đã lưu đệm. Bạn chỉ bắt buộc nhập lại manifest khi ghi chú phát hành nói vậy, hoặc khi plugin hiện biểu ngữ báo có bản mới. Đường dẫn cố định nên nhập lại chỉ mất một cú nhấp.

### Khởi động lại MCP client

Đóng hẳn rồi mở lại Claude Code, Cursor hay app bạn dùng để nó nạp cấu hình mới.

### Phương án khác: chạy từ mã nguồn

Nếu bạn muốn sửa code hoặc đóng góp, README có cách Local Git. Bạn cần Git và Node.js:

```bash
git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
npm install
npm run build:local
```

Sau đó trỏ cấu hình vào file đã build, nhớ thay đường dẫn tuyệt đối đúng với máy bạn:

```json
{
  "mcpServers": {
    "figma-console": {
      "command": "node",
      "args": ["/absolute/path/to/figma-console-mcp/dist/local.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
        "ENABLE_MCP_APPS": "true"
      }
    }
  }
}
```

Rồi làm tiếp các bước nhập plugin, khởi động lại và thử như ở trên.

### Phương án khác: chỉ đọc qua Remote SSE

Nếu chỉ muốn xem thử dữ liệu mà chưa cần sửa, README cho cách nhanh. Với Claude Desktop, vào Settings → Connectors → Add Custom Connector, đặt tên `Figma Console (Read-Only)` và URL `https://figma-console-mcp.southleft.com/sse`. Với Claude Code, README nói lệnh `--transport sse` gốc đang có lỗi nên dùng `mcp-remote`:

```bash
claude mcp add figma-console -s user -- npx -y mcp-remote@latest https://figma-console-mcp.southleft.com/sse
```

## Kiểm tra đã chạy được chưa

Mở lại client, rồi gõ hai câu theo README.

Câu thứ nhất:

```
Check Figma status
```

Kết quả đúng là hiện trạng thái kết nối, có transport WebSocket đang hoạt động. Nếu báo chưa kết nối, kiểm tra lại plugin đã chạy trong file Figma chưa.

Câu thứ hai:

```
Create a simple frame with a blue background
```

Nếu một frame nền xanh xuất hiện trong file Figma, nghĩa là quyền ghi đã thông. Bạn nên thử trong một file nháp, đừng thử trên file sản phẩm thật.

## Dùng vào việc thật

Các prompt dưới đây mình viết lại theo kiểu README gợi ý. Bạn có thể gõ tiếng Việt, AI vẫn gọi đúng công cụ, nhưng nếu không ra kết quả như ý thì thử lại bằng tiếng Anh.

### Chủ shop cần dựng nhanh một thẻ sản phẩm

Bạn bán hàng online, biết dùng Figma ở mức cơ bản và cần một mẫu thẻ sản phẩm. Mở file nháp, chạy plugin rồi nhờ AI:

```
Create a card component with a header image, title, description, and action button
```

AI tạo component ngay trong Figma. Bạn chỉnh chữ và màu theo thương hiệu. Bản nháp có trong vài phút thay vì phải dựng từng lớp.

> Đừng bắt AI vẽ cho thật đẹp ngay. Hãy để nó dựng khung, còn bạn chỉnh cho đúng thương hiệu.
>
> — Ông T

### Nhân viên thiết kế thêm chế độ tối cho bộ token

Công ty bạn có bộ biến màu, và sếp muốn thêm chế độ tương phản cao. Bạn chạy plugin trong file thư viện rồi gõ:

```
Add a "High Contrast" mode to my existing token collection
```

AI thêm một mode mới vào bộ biến sẵn có. Bạn tự rà lại các giá trị trước khi dùng, vì màu AI chọn cần mắt người duyệt. Muốn dựng bộ mới từ đầu, README có mẫu: `Set up a color token collection with Light and Dark modes`.

### Lập trình viên kiểm tra component có khớp với code

Bạn là dev frontend. Component Button trong Figma và trong code hay lệch nhau. Chọn component trong Figma và nhờ AI so khớp. README nói công cụ này so sánh theo hình ảnh, khoảng cách, chữ, token, API component và truy cập, dưới dạng kiểm tra xác định (deterministic). Bạn nhận danh sách chỗ lệch để sửa, thay vì ngồi so từng pixel.

### Quản lý design system chấm điểm sức khoẻ

Bạn đang giữ thư viện thiết kế của cả công ty. Hãy nhờ AI chạy bản kiểm tra sức khoẻ design system. README mô tả nó chấm điểm theo kiểu Lighthouse về đặt tên, token, metadata component, truy cập, tính nhất quán và độ phủ, kèm gợi ý sửa cho từng phát hiện. Bạn dùng điểm này để lập danh sách việc cần dọn trong tháng.

## Lỗi hay gặp và cách xử lý

**1. AI báo chưa kết nối Figma.** Thường do plugin chưa chạy. Mở file trong Figma Desktop, vào Plugins → Development và chạy lại Desktop Bridge. Plugin quét cổng 9223–9232, nên đảm bảo không có chương trình nào chặn các cổng đó.

**2. Không thấy server trong MCP client.** Nguyên nhân hay gặp là file JSON sai cú pháp hoặc chưa khởi động lại app. Kiểm tra dấu phẩy, ngoặc, rồi đóng hẳn app và mở lại. Nếu đã có mục `mcpServers`, đừng tạo mục thứ hai.

**3. Không tìm thấy thư mục plugin khi nhập manifest.** Trên macOS thư mục bắt đầu bằng dấu chấm bị ẩn. Dùng ⌘⇧G để dán đường dẫn, hoặc chạy `npx figma-console-mcp --print-path` để lấy đường dẫn chính xác.

**4. Sau khi nâng cấp, tính năng mới không chạy.** Figma lưu đệm file plugin, nên bản cũ vẫn chạy. Vào Plugins → Manage plugins và nhập lại `~/.figma-console-mcp/plugin/manifest.json`, nhất là khi ghi chú phát hành yêu cầu.

**5. Lệnh dài bị hết thời gian trên Codex.** Mặc định 10 giây và 60 giây của Codex quá ngắn. Thêm `startup_timeout_sec = 60` và `tool_timeout_sec = 300` vào `~/.codex/config.toml`. Với Google Antigravity, README dặn thêm `"timeoutSeconds": 300` vào mục server.

Ngoài ra, nếu bạn dùng Remote SSE mà đòi tạo hay sửa thiết kế thì sẽ không được, vì chế độ đó chỉ đọc. Hãy chuyển sang NPX hoặc Cloud Mode.

## Có nên dùng không

**Điểm mạnh.** Bộ công cụ rộng: đọc, tạo, sửa, đồng bộ token, kiểm tra truy cập, so khớp thiết kế với code, chấm sức khoẻ design system. Có nhiều đường kết nối, từ chỉ đọc đến ghi đầy đủ. Hỗ trợ nhiều client như Claude Code, Cursor, Codex, Gemini CLI. Giấy phép MIT và repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Bạn cần Figma Desktop và phải nhập plugin thủ công, nên với người chưa quen terminal và file JSON thì ban đầu hơi lòng vòng. Quyền Variables qua REST API chỉ dành cho Enterprise, theo README. Cloud Mode không có theo dõi thời gian thực. Phần quét codebase thành design system chỉ chạy ở chế độ trên máy. README bản mình có bị cắt giữa chừng, nên các chi tiết như giá hay giới hạn dùng đám mây mình chưa kiểm chứng.

**Khi nào nên chọn cách khác.** Nếu chỉ cần xem nhanh dữ liệu thì dùng Remote SSE là đủ. Nếu không muốn cài Node thì chọn Cloud Mode. Nếu chưa làm việc với Figma bao giờ thì nên học Figma cơ bản trước, vì AI chỉ giúp bạn nhanh hơn chứ không thay phần hiểu về thiết kế.

Lời khuyên của mình: thử trong một file nháp trước, đặt token ở mức quyền tối thiểu, và luôn duyệt lại kết quả AI tạo ra trước khi đưa vào file chính.

## 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ó thể chạy qua npx. Tư liệu mình có không nói gì về chi phí của dịch vụ đám mây hay của gói Figma, nên mục này mình chưa có thông tin. Bạn nên xem thêm tài liệu của dự án.

### Tôi có cần biết lập trình để cài không?

Bạn cần chạy được một lệnh trong terminal và sửa một file JSON nếu dùng Cursor, Windsurf hay Claude Desktop. Với Claude Code chỉ cần một lệnh `claude mcp add`. Nếu không muốn cài Node.js, README có Cloud Mode cho các AI chạy trên web.

### Có chạy được trên Windows không?

Có. README ghi cả đường dẫn file cấu hình trên Windows, ví dụ `%APPDATA%\Claude\claude_desktop_config.json`. Bạn cần Node.js 18+ và Figma Desktop.

### Có cần máy mạnh hay GPU không?

Tư liệu không đề cập yêu cầu phần cứng. Phần được nêu là Node.js 18 trở lên và Figma Desktop. AI chạy ở client mà bạn chọn, còn server này chỉ làm cầu nối.

### Tôi có thể dùng với Claude.ai trên web không?

Được, bằng Cloud Mode. Bạn thêm connector có URL `https://figma-console-mcp.southleft.com/mcp`, dùng token Figma làm Bearer token, rồi ghép plugin bằng mã 6 ký tự (hết hạn sau 5 phút). Cách này không cần Node.js nhưng vẫn cần Figma Desktop với plugin.

### Khác gì Remote SSE?

Remote SSE chỉ đọc: xem dữ liệu, chụp màn hình, đọc log. Nó không tạo hay sửa thiết kế. NPX và Cloud Mode cho quyền ghi, với khoảng 130 công cụ (NPX) hoặc 105 công cụ (Cloud Mode sau khi ghép nối).

### Dữ liệu thiết kế của tôi có an toàn không?

Tư liệu mình có không mô tả chi tiết về xử lý dữ liệu. Có file SECURITY.md trong repo để bạn xem chính sách. Mình khuyên bạn đặt token ở mức quyền tối thiểu và thử trên file nháp trước.
