figma-mcp-auth

Connect any MCP client to Figma's remote MCP server — even clients Figma doesn't officially support.

npx figma-mcp-auth all

The problem

Figma's remote MCP server (https://mcp.figma.com/mcp) is OAuth-only, and its OAuth server rejects RFC 7591 dynamic client registration from every client that isn't on Figma's catalog:

Only clients listed in the Figma MCP Catalog like VS Code, Cursor, or Claude Code can connect. — Figma docs

If your agent isn't in that list (ZCode, Windsurf, Trae, Cline, a home-grown agent, anything new), its login fails deterministically:

Dynamic Client Registration rejected (HTTP 403): Forbidden
MCP authorization was not completed or timed out. Authorize again.

Personal access tokens don't help either — Figma's remote server accepts OAuth only (no X-Figma-Token header, no PATs).

The fix

This tool mints a Figma MCP token through a client Figma does accept (the Codex CLI, or Claude Code), then injects it into your agent's MCP config as a static Authorization: Bearer header. Figma's server is perfectly happy serving tools to any client that presents a valid token — it just won't register unknown clients.

┌─────────────┐  codex mcp login (allow-listed)   ┌────────────┐
│ codex CLI   │ ──── browser → you click Allow ──▶│   Figma    │
│ (isolated   │ ◀── token stored in OS keyring ───│  OAuth     │
│  home)      │                                   └────────────┘
└──────┬──────┘
       │ figma-mcp-auth reads the keyring
       ▼
┌─────────────┐  Authorization: Bearer figu_…     ┌────────────┐
│ your agent  │ ◀── HTTP 200, tools available ───▶│   Figma    │
└─────────────┘                                   │ MCP server │
                                                  └────────────┘

What it does not do: touch your existing Codex or Claude setup (Codex runs in a throwaway CODEX_HOME), send your token anywhere except api.figma.com / mcp.figma.com, or store it anywhere but ~/.figma-mcp-auth/token.json and the agent configs you explicitly inject into.

Usage

npx figma-mcp-auth all          # diagnose → mint (browser approval) → inject

Step by step:

| Command | What it does | |---|---| | figma-mcp-auth doctor | Checks the endpoint, the stored token (live handshake), the DCR allow-list gate, and every known agent config | | figma-mcp-auth mint | Runs codex mcp login figma in an isolated home; you approve in the browser; token lands in ~/.figma-mcp-auth/token.json | | figma-mcp-auth inject --target zcode | Writes the Authorization header into ~/.zcode/cli/config.json (also: --target claude, --target cursor, or any JSON file via --config) | | figma-mcp-auth refresh | Exchanges the stored refresh token for a fresh access token and updates every config previously injected | | figma-mcp-auth all | doctor → mint (only if needed) → inject |

Supported config shapes (auto-detected):

// ZCode (~/.zcode/cli/config.json) — nested
{ "mcp": { "servers": { "figma": { "type": "http", "url": "https://mcp.figma.com/mcp",
    "headers": { "Authorization": "Bearer figu_…" } } } } }

// Claude Code / Cursor / .mcp.json — flat
{ "mcpServers": { "figma": { "type": "http", "url": "https://mcp.figma.com/mcp",
    "headers": { "Authorization": "Bearer figu_…" } } } }

After injecting, restart the agent (MCP servers connect at session start).

Requirements

• Node ≥ 18
• For mint: the Codex CLI installed and on PATH (Windows, macOS, Linux). Alternative without Codex: --client claude, which prints the two-step Claude Code flow and then adopts the token from ~/.claude/.credentials.json.
• A Figma account, and one click of Allow in the browser.

Token lifetime

Figma's MCP access tokens last 90 days (expires_in: 7776000). Note: figma-mcp-auth refresh only succeeds if the store contains the OAuth client_secret — Figma's token endpoint demands it for refresh and the Codex CLI does not retain it in its keyring blob. In practice, renewal means running figma-mcp-auth mint again (one browser click, roughly once per 90 days); the tool's refresh command detects this case and says so.

Known limits

• mint reads the token from the OS keyring where Codex stores it: Windows Credential Manager (works headlessly), macOS Keychain (security may show one permission prompt), Linux via secret-tool (best effort).
• Keyring layouts are reverse-engineered from the Codex CLI's behavior as of its 0.13x releases; if a future Codex version changes storage, mint will tell you and the manual steps in SKILL.md still apply.

For agent authors: the SKILL.md

This package ships SKILL.md — a drop-in skill file (frontmatter + procedure) that teaches any agent how to diagnose and fix this exact failure, including the fully manual fallback. Copy it into your agent's skills directory (e.g. ~/.agents/skills/figma-mcp-auth/SKILL.md, ~/.claude/skills/, …) or just let the agent run npx figma-mcp-auth doctor and read its output.

Publishing / running from source

git clone <this repo> && cd figma-mcp-auth
node bin/figma-mcp-auth.js doctor      # run without installing
npm link                               # or: npm i -g .
npm publish                            # makes `npx figma-mcp-auth` work for everyone

License

MIT. Unofficial community tool — not affiliated with or endorsed by Figma. Use with your own Figma account; the browser approval is always yours to give.