Content
# Figma CLI
> Figma MCP Command Line Tool — **Figma Bridge for AI Agents**
>
> 📖 For Figma MCP authentication issues, see: [Kimi Can't Use Figma? Check Here](https://juejin.cn/spost/7647784370972360755)
Bring Figma's full design read/write capabilities to the command line, designed specifically for **Claude Code / Cursor and other AI Agents**.
## Design Concept
This tool does not encapsulate the Figma REST API but acts as an **agent and frontend for the Figma Remote MCP Server**:
- **`figma mcp`** — Launch the stdio MCP agent for direct connection and usage of all Figma MCP tools by AI Agents
- **`figma use-figma`** / **`figma call`** — Directly invoke MCP tools from the terminal without an intermediate agent layer
- **`figma auth`** — One-stop authentication management (PAT + OAuth)
## Installation
```bash
pnpm link # Local link (for development)
# or
pnpm install -g @boltdoggy/figma # Global installation (after release)
```
> Alternatively, use `npx -y @boltdoggy/figma` to run without installation for temporary use or MCP configuration.
## Quick Start
### 1. Authentication
```bash
# Check authentication status
figma auth status
# Method A: OAuth login (recommended, supports full MCP capabilities)
figma auth oauth-login # Automatically open the browser to complete PKCE authorization
# Method B: Set Personal Access Token (required for read-only operations)
figma auth set figd_xxxxxxxxxxxx
figma auth test # Test PAT validity
```
### 2. Configure MCP Server (for AI Agents)
In Claude Code, Cursor, or Windsurf, register `figma mcp` as a stdio MCP Server.
**Method A — Direct reference after global installation** (already `pnpm link` or `npm i -g` locally):
| Platform | Configuration Location |
|------|--------------------|
| **Claude Code** | `.claude/settings.local.json` or `~/.claude/settings.json` |
| **Cursor** | `.cursor/mcp.json` |
| **Windsurf** | `.windsurf/mcp.json` |
```json
{
"mcpServers": {
"figma": {
"command": "figma",
"args": ["mcp"]
}
}
}
```
**Method B — Use `npx -y` to automatically fetch** (recommended):
```json
{
"mcpServers": {
"figma": {
"command": "npx",
"args": ["-y", "@boltdoggy/figma", "mcp"]
}
}
}
```
> The `npx -y` method does not require prior global installation and automatically downloads and runs the latest version each time. Suitable for initial configuration, cross-machine use, or CI environments.
After configuration, the Agent automatically obtains `use_figma`, `get_design_context`, `get_screenshot`, `search_design_system`, and other Figma MCP tools, allowing direct reading or writing of Figma design files.
### 3. Directly Operate Figma from the Terminal
```bash
# Parse Figma URL
figma url "https://figma.com/design/abc123/MyDesign?node-id=1-2"
# Create design in Figma file (inline code)
figma use-figma abc123 --code '
const frame = figma.createFrame()
frame.resize(375, 812)
frame.fills = [{type: "SOLID", color: {r: 1, g: 1, b: 1}}]
frame.name = "iPhone Frame"
figma.currentPage.appendChild(frame)
'
# Read design code from a file
figma use-figma abc123 -f ./my-design-code.js
# Call any MCP tool
figma call get_screenshot --arg.fileKey=abc123 --arg.nodeId=1-2
figma call get_design_context --arg.fileKey=abc123 --arg.nodeId=1-2
figma call search_design_system --arg.fileKey=abc123 --arg.query=button
```
## Command Reference
### `figma auth` — Authentication Management
| Subcommand | Function |
|--------|------|
| `figma auth set <token>` | Set Personal Access Token |
| `figma auth status` | View detailed status of PAT and OAuth |
| `figma auth clear` | Clear PAT |
| `figma auth test` | Test PAT validity (call `/v1/me`) |
| `figma auth oauth-login` | **OAuth Login** — Open browser to complete PKCE authorization flow |
| `figma auth oauth-logout` | Clear OAuth token |
### `figma mcp` — MCP Agent
Launch the **stdio MCP agent**, transparently passing all Figma Remote MCP Server tools to AI Agents.
```bash
figma mcp
```
This is the core capability: After Agents connect via stdio, they can obtain `use_figma`, `get_design_context`, `get_screenshot`, `search_design_system`, and other Figma MCP tools.
### `figma use-figma <fileKey>` — Execute Design Operations
Run JavaScript (Figma Plugin API) in the specified Figma file to complete creation, editing, synchronization, and other design operations.
| Option | Description |
|------|------|
| `-c, --code <code>` | Inline JS code |
| `-f, --file <path>` | Read JS code from a file |
| `-d, --description <desc>` | Operation description (default `figma-cli call`) |
### `figma call <toolName>` — Call Any MCP Tool
Universally call Figma MCP tools, passing parameters with `--arg.key=value`.
```bash
figma call get_screenshot --arg.fileKey=abc123 --arg.nodeId=1-2
figma call get_libraries --arg.fileKey=abc123
```
### `figma url <figmaUrl>` — URL Parsing
Extract `fileKey`, `nodeId`, and `branchKey` from a Figma URL.
## Authentication
### Personal Access Token (PAT)
Suitable for CI/CD or traditional REST API call scenarios.
```bash
figma auth set figd_xxxxxxxxxxxx
```
Can also be set via environment variables (higher priority):
```bash
export FIGMA_ACCESS_TOKEN=figd_xxxxxxxxxxxx
```
### OAuth 2.0 with PKCE (MCP Mode)
MCP complete read/write capabilities require OAuth authentication:
```bash
figma auth oauth-login
```
Flow:
1. Discover Figma OAuth endpoint
2. Dynamically register OAuth client
3. Launch local callback server → Open browser for authorization
4. Exchange access + refresh token using PKCE
5. Persistently store tokens for subsequent automatic reuse
> **Note:** Figma Remote MCP Server is currently in beta. Starter free accounts limit MCP tool calls to 6 per month. OAuth client credentials must be in Figma OAuth whitelist.
## Tech Stack
- **TypeScript** — Type safety
- **Commander.js** — CLI framework
- **@modelcontextprotocol/sdk** — MCP protocol (Stdio Server + Streamable HTTP Client)
- **Chalk + Ora** — Color output and loading animation
- **Conf** — Configuration file persistence
- **Figma Remote MCP Server** — Complete design read/write capabilities
## Blog
Detailed explanation of Figma MCP authentication issues: [Kimi Can't Use Figma? Check Here](https://juejin.cn/spost/7647784370972360755)
## Development
```bash
# Install dependencies
pnpm install
# Type checking
pnpm typecheck
# Compile
pnpm build
# Development mode (run ts directly)
pnpm dev -- <args>
# Release version
pnpm build && figma <command>
```
