# 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

> figma-console-mcp là một MCP server giúp trợ lý AI như Claude đọc và ghi trực tiếp vào Figma: lấy token, component, biến, tạo khung thiết kế, kiểm tra accessibility và sức khoẻ design system. Cài bằng một lệnh npx cộng một plugin nhập vào Figma Desktop. Với người đã quen terminal thì khá dễ, người mới cần khoảng 10 phút.

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

figma-console-mcp là một MCP server (cầu nối cho AI) giúp các trợ lý như Claude, Cursor hay Codex nói chuyện trực tiếp với Figma. AI không chỉ đọc được thiết kế của bạn mà còn tạo khung, component, biến (variables) và kiểm tra lỗi ngay trong file Figma đang mở.

Repo này hợp với nhà thiết kế UI/UX, lập trình viên front-end và nhóm làm design system. Bạn sẽ đỡ phải chép tay màu sắc, khoảng cách, font từ Figma sang code. Tác giả mô tả ngắn gọn: "Your design system as an API", nghĩa là design system của bạn trở thành dữ liệu có cấu trúc để AI dùng.

Điểm đáng giá nhất là repo hoạt động hai chiều và **ghi được vào Figma**, không chỉ đọc. Ngoài ra nó có các bước kiểm tra cố định (không phải AI đoán) cho độ khớp giữa thiết kế và code, khả năng tiếp cận (accessibility) và sức khoẻ design system. Repo hiện có khoảng 3297 sao và 302 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây. Bạn xem video ngắn bên dưới để thấy nó chạy thế nào, rồi quay lại làm theo từng bước.

```repo
- repo | southleft/figma-console-mcp
- kind | MCP server
- desc | MCP server nối AI (Claude, Cursor…) với Figma: đọc design system, tạo khung và component, quản lý biến, kiểm tra accessibility ngay trong file Figma.
- 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 có tới 130 công cụ (tool) khi cài kiểu NPX hoặc Local Git. Mình gom lại thành các nhóm bạn dễ hình dung.

**Đọc và trích xuất design system.** AI kéo được biến, component và style từ file Figma. Bạn khỏi mở từng frame để chép giá trị. AI nhận đúng token, variant, trạng thái dưới dạng dữ liệu có cấu trúc, nên code sinh ra bám theo stack và quy ước của đội bạn, không bị áp một phong cách có sẵn.

**Đồng bộ token hai chiều.** Bạn xuất biến Figma sang JSON theo chuẩn DTCG và 9 định dạng khác. Sửa bên code xong, bạn đẩy ngược lại Figma: tạo mới, đổi tên, đổi liên kết alias, xoá có kiểm soát. Tác giả nói tính năng này thay được đường xuất của Style Dictionary và Tokens Studio.

**Tạo và sửa thiết kế.** AI tạo khung, layout, component ngay trong Figma, kể cả tạo cả bộ component set từ một ma trận variant chỉ bằng một lần gọi. Bản mới nhất ghi trong README (v1.46.0) còn thêm auto layout hoặc grid trong một lệnh, màu OKLCH và Display P3, shader, và các tuỳ chọn chữ như text wrap.

**Quản lý biến.** Tạo, cập nhật, đổi tên, xoá token. Bạn có thể nhờ AI dựng bộ màu có hai chế độ Light và Dark.

**Kiểm tra tự động.** Có 14 phép kiểm tra thiết kế theo WCAG, so sánh deterministic giữa component Figma và code, và một bản audit chấm điểm kiểu Lighthouse cho tên gọi, token, metadata component, accessibility, tính nhất quán và độ phủ.

**Gỡ lỗi trực quan và theo dõi thời gian thực.** AI chụp màn hình để hiểu ngữ cảnh, và xem được console log từ plugin Desktop Bridge. Phần theo dõi thời gian thực chỉ có ở chế độ chạy trên máy (NPX hoặc Local Git).

**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.

**FigJam và Slides.** AI tạo sticky, flowchart, bảng, khối code trên FigJam, và dựng bộ slide trong Figma Slides.

**Nhiều cách kết nối.** Có bốn cách: Remote SSE (chỉ đọc), Cloud Mode (cho AI chạy trên web), NPX và Local Git.

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

Với cách khuyến nghị (NPX), README yêu cầu:

- **Node.js 18 trở lên.** Kiểm tra bằng `node --version`. package.json cũng ghi Node >= 18.0.0.
- **Figma Desktop** đã cài. Chỉ có bản web là chưa đủ.
- **Một MCP client**: Claude Code, Cursor, Windsurf, Claude Desktop, Codex, Gemini CLI, Google Antigravity…
- **Figma personal access token** (chuỗi bắt đầu bằng `figd_`). Cách tạo nằm ở Bước 1 bên dưới.

README không nói gì về yêu cầu GPU hay cấu hình máy, và phần tài liệu mình có không ghi rõ hệ điều hành tối thiểu. Có điều phần hướng dẫn đường dẫn file cấu hình có ghi cả macOS lẫn Windows, nên Windows dùng được.

Nếu bạn dùng AI trên web (Claude.ai, v0, Replit, Lovable) và không muốn cài Node.js, hãy xem Cloud Mode ở cuối phần cài đặt. Cloud Mode vẫn cần Figma Desktop cùng plugin.

```note
Figma token có quyền đọc file thiết kế của bạn (và ghi comment nếu bạn cấp). Đừng dán token vào ảnh chụp màn hình, tin nhắn nhóm hay file commit lên GitHub. Token chỉ hiện đúng một lần khi tạo, nên hãy lưu ở nơi an toàn.
```

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

```steps
- Tạo Figma token | Tạo personal access token, cấp các quyền đọc cần thiết
- Thêm vào MCP client | Chạy lệnh hoặc sửa file JSON cấu hình để client khởi động figma-console-mcp bằng npx
- Nhập plugin Desktop Bridge | Trong Figma Desktop, import plugin từ file manifest rồi chạy nó
- Khởi động lại MCP 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 nhờ AI tạo một frame
```

### Lấy Figma token

Vào trang trợ giúp của Figma, mục "Manage personal access tokens", rồi tạo token mới. README hướng dẫn như sau:

1. Đặt mô tả là `Figma Console MCP`.
2. Chọn quyền (scope), tất cả để mức Read trừ khi ghi chú khác: **File content**, **File versions**, **Library content**, **Library assets**, **Comments** (Read and write), **Current user**. Riêng **Variables** chỉ dành cho gói Enterprise và là tuỳ chọn.
3. Sao chép token ngay, vì Figma chỉ hiện một lần. Token bắt đầu bằng `figd_`.

Chỗ người mới hay vấp: đóng cửa sổ trước khi chép token thì phải tạo lại token khác.

### Thêm vào MCP client

Chọn đúng client bạn đang dùng. Thay `figd_YOUR_TOKEN_HERE` bằng token thật.

**Claude Code (chạy trong terminal):**

```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ý một MCP server tên `figma-console`, truyền token qua biến môi trường và chạy gói npm bằng `npx`. README nói dùng Claude Code thì bạn khỏi sửa file thủ công.

**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
```

Sau đó, trong file `~/.codex/config.toml`, README yêu cầu đặt `startup_timeout_sec = 60` và `tool_timeout_sec = 300` cho server này, vì mặc định 10 giây và 60 giây của Codex quá ngắn.

**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
```

**Cursor, Windsurf, Claude Desktop:** mở file cấu hình MCP của app và thêm đoạn JSON sau.

```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: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
- Cursor: `~/.cursor/mcp.json` hoặc `%USERPROFILE%\.cursor\mcp.json`.
- Windsurf: `~/.codeium/windsurf/mcp_config.json` hoặc `%USERPROFILE%\.codeium\windsurf\mcp_config.json`.
- Claude Code: `~/.claude.json` hoặc `%USERPROFILE%\.claude.json`.

Dấu `~` là thư mục gốc của bạn. Trên Windows là `C:\Users\TenBan\`. Nếu file chưa có, cứ tạo mới. Lưu ý toàn bộ file phải là JSON hợp lệ, thiếu dấu phẩy hay ngoặc là app không đọc được.

Với Google Antigravity, README bảo thêm cùng đoạn JSON vào `~/.gemini/config/mcp_config.json` và thêm `"timeoutSeconds": 300` trong mục server.

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

Muốn AI ghi được vào Figma, bạn cần plugin này. Làm theo README:

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`. Đường dẫn này được MCP server tự tạo. Chạy lệnh dưới đây để in ra đường dẫn chính xác trên máy bạn:

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

4. Chạy plugin trong file Figma. Plugin tự quét cổng 9223–9232 và kết nối với MCP server đang chạy.

Chỗ hay vấp: 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, 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. Ngoài ra, MCP server phải chạy thì plugin mới có gì để kết nối, nên hãy mở client trước.

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

Đóng hẳn rồi mở lại client (Claude Desktop, Cursor…) để nó nạp cấu hình mới. Với Claude Code, mở phiên mới.

### Cách khác: Local Git, Remote SSE, Cloud Mode

**Local Git** dành cho người muốn sửa mã nguồn. Cũng có đủ 130 công cụ.

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

Rồi cấu hình client trỏ tới 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"
      }
    }
  }
}
```

**Remote SSE** chỉ đọc, hợp để xem thử. Với Claude Desktop: 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 cảnh báo cờ `--transport sse` đang gặp 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
```

**Cloud Mode** dành cho AI trên web, không cần Node.js, mở khoá 105 công cụ sau khi ghép cặp. Thêm connector với URL `https://figma-console-mcp.southleft.com/mcp`, dùng Figma token làm Bearer token. Sau đó mở plugin Desktop Bridge trong Figma, nói với AI "Connect to my Figma plugin", AI đưa mã ghép cặp 6 ký tự (hết hạn sau 5 phút). Bạn bật "Cloud Mode" trong plugin, nhập mã và bấm Connect.

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

Sau khi khởi động lại client và chạy plugin trong Figma, gõ hai câu theo README:

```
Check Figma status
```

Kết quả mong đợi: AI báo trạng thái kết nối, có nhắc đang dùng WebSocket.

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

Kết quả mong đợi: một frame nền xanh xuất hiện trong file Figma của bạn. Nếu thấy, nghĩa là quyền ghi đã thông. Nếu câu đầu báo chưa kết nối, hãy kiểm tra plugin đã chạy chưa (xem mục lỗi thường gặp).

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

Các tình huống dưới đây bám vào khả năng README liệt kê. Câu lệnh mẫu mình viết ra để bạn tham khảo, bạn chỉnh theo file của mình.

### Dựng nhanh một component thẻ sản phẩm

Bạn là designer của một shop online, cần thẻ sản phẩm có ảnh, tiêu đề, mô tả và nút mua. Thay vì vẽ từng lớp, bạn mở file, chạy plugin và nhờ AI. README có đúng câu mẫu tương tự:

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

Bạn nhận về một component trong Figma để chỉnh tiếp. Muốn làm ra nhiều biến thể (cỡ nhỏ, vừa, lớn), README nói có thể tạo component set từ một ma trận variant chỉ trong một lần gọi.

### Thêm chế độ Dark Mode cho bộ màu

Bạn là nhân viên văn phòng phụ trách thương hiệu của công ty, có sẵn bộ màu và cần thêm giao diện tối. Bạn hỏi:

```
Set up a color token collection with Light and Dark modes
```

hoặc với bộ đã có:

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

Kết quả là bộ biến (variables) có thêm mode mới, không phải tạo tay từng màu. Cloud Mode làm được việc này kể cả trên gói Figma không phải Enterprise, vì nó dùng Plugin API thay cho REST API của Enterprise.

> Công cụ này biến design system của bạn thành dữ liệu để AI dùng, nên bạn không phải chép tay từng giá trị nữa.
>
> — Ông T

### Xuất token cho đội lập trình

Bạn là front-end dev và designer vừa cập nhật màu, khoảng cách trong Figma. Bạn nhờ AI xuất biến Figma ra JSON theo chuẩn DTCG (README nói hỗ trợ thêm 9 định dạng khác), rồi đưa vào dự án. Khi code sửa token, bạn đẩy ngược lại Figma. Hai bên dùng chung một nguồn sự thật.

### Rà soát design system trước khi bàn giao

Bạn là trưởng nhóm design, cần biết file đã gọn chưa trước khi giao cho dev. Bạn nhờ AI chạy audit sức khoẻ design system (chấm điểm theo tên gọi, token, metadata component, accessibility, nhất quán, độ phủ) hoặc quét 14 phép kiểm tra WCAG. README nói audit có hướng dẫn tự sửa cho từng phát hiện. Bạn nhận một danh sách lỗi cụ thể để xử lý trước khi bàn giao. Đây là kiểm tra cố định theo quy tắc, chứ không phải AI nhận xét cảm tính.

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

**AI báo chưa kết nối với Figma.** Thường do plugin Desktop Bridge chưa chạy trong file đang mở, hoặc client chưa khởi động lại sau khi cấu hình. Hãy mở Figma Desktop (không phải bản web), mở file, chạy plugin, rồi hỏi lại "Check Figma status". Plugin quét cổng 9223–9232 nên đừng để chương trình khác chiếm hết dải cổng đó.

**Không thấy folder `.figma-console-mcp` khi nhập plugin.** Thư mục bắt đầu bằng dấu chấm nên macOS ẩn 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.

**Cập nhật xong mà plugin vẫn như cũ.** README giải thích Figma lưu bộ nhớ đệm file plugin. MCP server tự làm mới file mỗi lần khởi động, nhưng Figma vẫn dùng bản cũ cho đến khi bạn nhập lại manifest. Chỉ cần nhập lại khi ghi chú phát hành bảo vậy, hoặc khi plugin hiện biểu ngữ báo có bản mới. Cách làm: Plugins → Manage plugins → nhập lại `~/.figma-console-mcp/plugin/manifest.json`.

**File cấu hình JSON không được nạp.** Hay do thiếu dấu phẩy hoặc ngoặc, hoặc đặt file sai chỗ. Kiểm tra lại cú pháp JSON và đường dẫn theo bảng ở trên. Nếu dùng Claude Code, dùng lệnh `claude mcp add` để khỏi sửa tay.

**Codex báo hết thời gian chờ.** README nói mặc định 10 giây khởi động và 60 giây cho mỗi công cụ là quá ngắn. Đặt `startup_timeout_sec = 60` và `tool_timeout_sec = 300` trong `~/.codex/config.toml`.

**Claude Code không kết nối được Remote SSE.** README ghi đây là lỗi đã biết của `--transport sse`. Dùng lệnh `mcp-remote` ở trên thay thế.

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

**Điểm mạnh.** Đây là một trong số ít công cụ cho AI ghi thật vào Figma, không chỉ đọc. Bộ 130 công cụ phủ nhiều việc: trích token, tạo thiết kế, đồng bộ hai chiều, kiểm tra accessibility, audit design system. Giấy phép MIT, cộng đồng khá lớn, và repo còn được cập nhật.

**Giới hạn.** Cần Figma Desktop và cài thêm plugin, nên không phải "cắm vào là chạy". Phần theo dõi thời gian thực chỉ có khi chạy trên máy. Cloud Mode có 105 công cụ thay vì 130, và Remote SSE chỉ đọc. Quyền Variables qua REST API cần gói Enterprise, dù Cloud Mode có đường vòng bằng Plugin API. Phần README mình có bị cắt ở giữa, nên chi phí và chi tiết nâng cao bạn nên xem thêm trong tài liệu của dự án (thư mục `docs/` và trang docs của tác giả).

**Khi nào chọn cách khác.** Nếu bạn chỉ cần xuất token một lần và không dùng AI, một công cụ xuất token chuyên dụng có thể gọn hơn. Nếu bạn không dùng Figma, repo này không có ích gì. Nếu bạn chỉ muốn xem thử mà chưa muốn cài gì, hãy bắt đầu với Remote SSE chỉ đọc, rồi nâng cấp lên NPX khi thấy hợp.

## 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à cài qua npm, tức mã nguồn mở. Phần tài liệu mình có không nói gì về phí của dịch vụ cloud do tác giả vận hành. Bạn vẫn cần Figma Desktop và một MCP client của riêng mình, và các công cụ đó có chính sách phí riêng.

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

Tư liệu không nhắc tới yêu cầu GPU hay cấu hình phần cứng. Yêu cầu duy nhất được ghi là Node.js 18 trở lên (với cách NPX), Figma Desktop và một MCP client.

### Chạy trên Windows được không?

Được. README có ghi sẵn đường dẫn file cấu hình cho cả macOS lẫn Windows, ví dụ `%USERPROFILE%\.cursor\mcp.json` cho Cursor. Thư mục plugin `.figma-console-mcp` hiện bình thường trên Windows.

### AI có sửa hỏng file Figma của tôi không?

Ở chế độ NPX, Local Git và Cloud Mode, AI có quyền ghi: tạo, sửa, đổi tên, xoá biến và layer. Tư liệu mình có không nói gì về cơ chế hoàn tác riêng. Bạn nên thử trên file nháp hoặc bản sao trước, và nhớ Figma có lịch sử phiên bản. Remote SSE thì chỉ đọc nên an toàn hơn để xem thử.

### Khác gì Remote SSE, Cloud Mode và NPX?

Remote SSE chỉ đọc, cài nhanh nhất (khoảng 2 phút theo README). Cloud Mode cho AI trên web như Claude.ai, v0, Replit ghi vào Figma qua ghép cặp plugin, có 105 công cụ và không cần Node.js. NPX và Local Git cho đủ 130 công cụ, kèm theo dõi thời gian thực và quét codebase.

### Tôi không dùng gói Figma Enterprise thì sao?

Quyền Variables của token chỉ dành cho Enterprise và là tuỳ chọn. README nói Cloud Mode dùng Plugin API thay vì REST API của Enterprise, nên làm việc với biến được trên mọi gói. Tư liệu mình có chưa nói rõ chế độ NPX xử lý biến trên gói thường ra sao.

### Token Figma của tôi có an toàn không?

Token được đặt trong cấu hình MCP client trên máy bạn (biến FIGMA_ACCESS_TOKEN). Với Cloud Mode, token được gửi dưới dạng Bearer token tới máy chủ cloud của dự án. Repo có file SECURITY.md, nhưng tư liệu mình có chưa nêu chi tiết cách lưu trữ. Bạn chỉ cấp quyền cần thiết và đừng chia sẻ token.
