figma-proxy-mcp

A local MCP (Model Context Protocol) server that gives AI coding agents direct, live access to your open Figma file — purpose-built for engineers doing design handoff and UX writers managing copy at scale.

No Figma API token. No rate limits. No stale exports. The AI reads exactly what is currently open in Figma.

Why this exists

Design handoff is slow because engineers have to manually translate Figma specs into code, and UX writers have to hunt through screens to audit copy. Both workflows become faster when an AI agent can read the live design directly:

• Engineers can ask: "Give me the CSS for this card component" or "Convert this entire page to HTML" and get production-ready output.

• UX Writers can ask: "Find every screen with placeholder lorem ipsum" or "Are the button labels consistent across all pages?" and get an answer in seconds.

Related MCP server: figma-mcp-write-server

Architecture

AI Agent (Claude, Cursor, etc.)
        |
        | MCP (Streamable HTTP)
        v
  MCP Server :3001          ← translates MCP tool calls to RPC
        |
        | HTTP POST /rpc
        v
  WebSocket Proxy :3000     ← routes requests to the right Figma file
        |
        | WebSocket
        v
  Figma Plugin              ← runs inside Figma Desktop, executes commands
        |
        | Plugin API
        v
  Live Figma File

Three services, each with a single responsibility:

Prerequisites

• Node.js 22+

• Figma Desktop app (the plugin requires the desktop plugin API)

• An AI client that supports MCP (Claude Desktop, Cursor, Windsurf, etc.)

Setup

1. WebSocket Proxy

cd websocket
npm install
npm run dev
# Running on http://localhost:3000

2. MCP Server

cd mcp-server
npm install
npm run dev
# Running on http://localhost:3001/mcp

Optionally set MCP_API_KEY to require a bearer token:

MCP_API_KEY=mysecret npm run dev

3. Figma Plugin

Build the plugin once:

cd plugin
npm install
npm run build

Load it in Figma Desktop:

1. Open Figma Desktop

2. Go to Plugins > Development > Import plugin from manifest

3. Select plugin/manifest.json

4. Run the plugin from the Plugins menu — it will appear as a small status panel

The plugin connects to the WebSocket proxy automatically. The status dot turns green when connected.

By default the plugin connects to ws://localhost:3000. To connect to a different host, type the WebSocket URL in the plugin panel and click Connect. The URL is saved and restored on next open.

4. Connect your AI client

Add the MCP server to your AI client config:

Claude Code CLI — add to your project's .mcp.json or run:

claude mcp add figma --transport http http://localhost:3001/mcp

For a tunneled remote server with API key:

claude mcp add figma --transport http https://your-tunnel.example.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude.ai web — go to Settings → Integrations → Add MCP server:

• URL: https://your-tunnel.example.com/mcp

• If API key is set, add header Authorization: Bearer YOUR_API_KEY

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

Cursor / Windsurf: Add http://localhost:3001/mcp as an MCP server in settings.

Docker

Both backend services have Dockerfiles using a multi-stage esbuild bundle. A single node:22-alpine image with no node_modules:

# WebSocket proxy
docker build -t figma-proxy-websocket ./websocket
docker run -p 3000:3000 figma-proxy-websocket

# MCP server (point it at the proxy)
docker build -t figma-proxy-mcp-server ./mcp-server
docker run -p 3001:3001 -e PROXY_URL=http://host.docker.internal:3000 figma-proxy-mcp-server

Environment variables

Available Tools

Design Inspection

CSS & Layout — for engineering handoff

Components & Variables — for token-driven development

HTML Codegen — skip the spec, get the code

Images & Assets

UX Writing & Copy Audit

Usage Examples

Design handoff: get implementation-ready specs

"Get the CSS for the selected card component, including its auto-layout and border spec."

The agent calls get_selection, then get_css, get_layout_spec, and get_stroke_spec on the result — and returns a ready-to-copy CSS block.

"Convert the Login page to HTML."

to_html_page({ page: "Login" })

Returns a full HTML document with inline CSS. Paste into your project as a starting point.

"What design tokens does this button use?"

get_node_variable_bindings({ nodeId: "4029:512" })

Returns every variable bound to that node — color tokens, spacing tokens, and their resolved values per mode (light/dark).

UX Writing: audit and update copy at scale

"Find every screen that still has placeholder text."

find_placeholders({})

Returns node IDs, page names, and the placeholder content — sorted by page.

"Are the CTA button labels consistent across the app?"

find_text_nodes({ regex: "(Get started|Start free|Try now|Sign up)" })
check_text_consistency({ group_by: "page" })

The agent cross-references both results and flags pages where labels deviate.

"Update the hero headline on the Landing page to: 'Ship faster with AI-native tooling'"

set_text_content({ nodeId: "3910:220", text: "Ship faster with AI-native tooling" })

The change appears live in Figma immediately.

"Show me all text that is clipped and not fully visible."

detect_text_overflow({})

Returns every text node overflowing its parent container, with node IDs so the designer can fix the layout.

Multi-file support

If you have multiple Figma files open with the plugin running in each, pass a fileKey to any tool to target a specific file:

get_document({ fileKey: "abc123XYZ" })

Omit fileKey when only one file is connected — the proxy routes to the single active connection automatically.

CI/CD

A GitHub Actions workflow (.github/workflows/docker-build-push.yml) builds and pushes both services to GitHub Container Registry on every push to main:

ghcr.io/<owner>/figma-proxy-mcp/mcp-server:latest
ghcr.io/<owner>/figma-proxy-mcp/mcp-server:<git-sha>

ghcr.io/<owner>/figma-proxy-mcp/websocket:latest
ghcr.io/<owner>/figma-proxy-mcp/websocket:<git-sha>

No extra secrets needed — uses GITHUB_TOKEN.