Framelink Figma MCP

What It Does

Framelink Figma MCP (npm package figma-developer-mcp) is a Model Context Protocol server that gives AI coding agents read access to Figma design files. When a user pastes a Figma URL into their agent, the server fetches the file or node from the Figma REST API, simplifies the response down to the layout, styling, and content details that matter for generating code, and returns that compact representation to the LLM. It exposes two tools: get_figma_data (read-only, fetches and simplifies a file or node) and download_figma_images (saves SVG, PNG, or GIF assets to a local directory). It supports both stdio and HTTP (StreamableHTTP plus SSE backward compatibility) transports, Personal Access Token and OAuth authentication, and works with Cursor, Claude Code, Windsurf, GitHub Copilot, and any standards-compliant MCP client. It targets developers and teams who want to turn Figma designs into working UI without pasting screenshots.

The Good

The error messages are the best in the MCP ecosystem. When a Figma API call returns 403 Forbidden, the server does not just surface the raw HTTP status. It returns a structured response that lists five concrete causes (missing scopes, revoked token, file not shared, share settings blocking export, corporate proxy), links to a troubleshooting guide, and ends with an instruction telling the LLM to explain the specific reason in plain language and walk the user through fixing it. I verified this directly: calling get_figma_data with a test key produced a 403 and the server returned isError: true with the full diagnostic block. Most MCP servers return a bare string on failure. This one returns a debugging manual.

250 tests pass across 18 test files (4,286 lines of test code). The suite covers the MCP handshake, tool registration, serialization, tree output, gradient handling, layout alignment, image processing, telemetry redaction, validation rejection, HTTP header auth, and path validation. I ran npx vitest run from a fresh clone and got Test Files 18 passed | 1 skipped (19) and Tests 250 passed | 1 skipped (251) in 4.73 seconds. The one skipped test is an integration test that needs live Figma credentials, which is the correct thing to skip.

Path-traversal defense in the download tool is thorough and well-documented. The download_figma_images tool accepts a localPath argument. The resolver (src/utils/local-path.ts) rejects absolute paths that resolve outside the configured image directory, rejects Windows drive-letter paths on POSIX hosts, and normalizes backslashes to forward slashes so an LLM can use either separator. I tested this: calling the tool with localPath=/etc/passwd returned isError: true with a message explaining the path resolves outside the allowed directory and suggesting the user drop the leading slash. The code comments document why the older path.join approach was replaced (it silently miswrote files to a doubled-up directory).

Token-efficient tree output format as the default. The server serializes simplified design data in three formats: tree (default), yaml, and json. The tree format encodes structural keys (id, name, type, children) positionally on each node line instead of repeating them as YAML or JSON keys, and deduplicates repeated styles into a globalVars block at the top. The CHANGELOG notes tree is roughly half the size of YAML. For LLM consumers where every token costs money and attention, this is a meaningful design choice that most MCP servers never consider.

Telemetry redaction prevents leaking secrets. The server uses PostHog for usage telemetry, but a dedicated test (telemetry-redaction.test.ts) verifies that per-request X-Figma-Token values are scrubbed from telemetry error messages before they leave the process. I confirmed this in the test output: the redacted error message showed token=figd_TENANT_SECRET_xyz789 being stripped. The server also masks the API key in its startup configuration output (****-key instead of the full token).

Clean MCP compliance with proper annotations. The get_figma_data tool carries a readOnlyHint: true annotation and the download_figma_images tool carries openWorldHint: true. Both tools have JSON schemas with additionalProperties: false, regex-validated parameters (file keys must be alphanumeric, node IDs must match a specific pattern), and the server declares taskSupport: forbidden. The repo ships a server.json for MCP registry compatibility. This is the level of MCP detail that official servers aim for.

The Bad

Telemetry is on by default. The server collects usage data via PostHog from the moment you run it. The startup output prints "Usage telemetry enabled. Disable: FRAMELINK_TELEMETRY=off or DO_NOT_TRACK=1" but you have to read the console to notice. For an agent tool that sits in your development environment and processes your design files, shipping with analytics enabled is a privacy posture that not every team will accept. There is no prompt or config-file setting that makes the opt-out obvious before first run. The --no-telemetry flag exists but is not mentioned in the README's setup instructions.

The server.json version is stale. The server.json file (used by MCP registries to discover and install the server) reports version 0.6.4 while package.json is at 0.13.2. The .release-please-manifest.json also shows 0.6.4. This means registry consumers may see an outdated version, and the metadata lag suggests the release process does not bump server.json in lockstep with the npm package. It is a metadata defect, not a functional one, but it affects how the server appears in directories.

The README is thin and leans heavily on an external docs site. The README is 95 lines and covers the one-line pitch, a demo video, a basic JSON config snippet, and a star history chart. Setup troubleshooting, output format details, the fetch CLI subcommand, HTTP mode, OAuth setup, proxy configuration, and the --image-dir flag are all documented on framelink.ai rather than in the repo. Developers who want a self-contained reference or who work offline will need to consult the hosted docs. The repo does compensate with strong inline code comments, a detailed CHANGELOG (288 lines), a ROADMAP (125 lines), SECURITY.md, and CONTRIBUTING.md.

End-to-end testing requires a Figma token and an accessible file. The server cannot function without Figma API credentials, and the most valuable feature (the simplification pipeline that turns a raw Figma file into compact LLM-ready data) only runs on real Figma data. The project's test suite covers the simplification logic with fixtures, but a reviewer or new user without a Figma account can only verify that the server starts, lists tools, and returns clean auth errors. This is inherent to the architecture, not a bug, but it raises the barrier for hands-on evaluation.

Smoke Test Results

All tests run on macOS (host), aarch64, Node v24.13.1. Two test environments were used: a clean npm cache for the npx install path, and a project directory with the inspector and server installed locally for the MCP probes.

Run A. Fresh npx install, no deps preinstalled

$ npx -y figma-developer-mcp@0.13.2 --version
✅ 0.13.2

$ npx -y figma-developer-mcp@0.13.2 --help
✅ Lists 1 command (fetch) and 14 flags

$ npx -y figma-developer-mcp@0.13.2 fetch --help
✅ Lists fetch flags (depth, file-key, node-id, format, json, etc.)

$ npx -y figma-developer-mcp@0.13.2 fetch --figma-api-key=test-key "https://www.figma.com/design/abc123xyz/Test?node-id=1234-5678"
✅ URL parsed correctly: fileKey=abc123xyz, nodeId=1234:5678
✅ API call reached Figma, returned clean 403 with troubleshooting guide

Pass rate: 4 of 4. The npx path installs and runs with zero configuration beyond a Figma key. URL parsing converts the - separator to : as expected.

Run B. MCP inspector probes (deps preinstalled)

$ npm install @modelcontextprotocol/inspector figma-developer-mcp@0.13.2
✅ 298 packages installed, 0 vulnerabilities

$ mcp-inspector --cli --config mcp-config.json --server figma --method tools/list
✅ Returns 2 tools (get_figma_data, download_figma_images)
✅ Schemas include additionalProperties:false, required arrays, regex patterns
✅ Annotations present (readOnlyHint, openWorldHint), taskSupport: forbidden

$ mcp-inspector --cli --config ... --method tools/call --tool-name get_figma_data --tool-arg fileKey=abc123test
✅ Returns isError:true with 403 body and 5-cause troubleshooting guide

$ mcp-inspector --cli --config ... --method tools/call --tool-name does_not_exist
✅ Returns isError:true, MCP error -32602 (Tool not found)

$ mcp-inspector --cli --config ... --method tools/call --tool-name download_figma_images --tool-arg localPath=/etc/passwd ...
✅ Path-traversal rejected: "resolves outside the allowed image directory"

$ mcp-inspector --cli --config ... --method resources/list
✅ Returns -32601 Method not found (server declares no resources, expected)

$ mcp-inspector --cli --config ... --method prompts/list
✅ Returns -32601 Method not found (server declares no prompts, expected)

Pass rate: 6 of 6. Every probe returned the correct result. The server handles happy paths, error paths, and adversarial inputs (path traversal) cleanly.

Run C. HTTP server mode and project test suite

$ node dist/bin.js --figma-api-key=test-key --port 3838
✅ HTTP server starts, prints masked config, listens on 127.0.0.1:3838
✅ StreamableHTTP at /mcp, SSE backward compat at /sse

$ curl -X POST http://127.0.0.1:3838/mcp -d '{"method":"initialize",...}'
✅ Returns protocolVersion 2025-06-18, capabilities.tools.listChanged:true, serverInfo

$ npx vitest run (from repo clone)
✅ Test Files 18 passed | 1 skipped (19)
✅ Tests 250 passed | 1 skipped (251)
✅ Duration 4.73s

Functional pass rate: 3 of 3. HTTP transport, MCP handshake over HTTP, and the full test suite all pass.

What the runs tell you

The server installs in one npx command, starts in both stdio and HTTP modes, and responds correctly to every MCP probe in the standard 8-check sequence. The only thing that cannot be verified without a real Figma account is the actual design simplification output, but the project's own 250-test suite exercises that pipeline with fixtures. The error handling is the standout: a failed API call produces a structured, actionable response instead of a stack trace.

Setup Walkthrough

1. Get a Figma Personal Access Token from your Figma account settings (Settings, under "Personal access tokens"). The token needs "File content: Read" and "Dev resources: Read" scopes.
2. Add the server to your MCP client config. For Cursor, Claude Code, or any client that reads an mcpServers JSON block:

 {
 "mcpServers": {
 "Framelink MCP for Figma": {
 "command": "npx",
 "args": ["-y", "figma-developer-mcp", "--figma-api-key=YOUR-KEY", "--stdio"]
 }
 }
 }

1. Restart your MCP client. Paste a Figma file, frame, or node URL into your agent chat and ask it to implement the design.
2. For HTTP mode instead of stdio: run npx -y figma-developer-mcp --figma-api-key=YOUR-KEY --port 3333 and point your client at http://127.0.0.1:3333/mcp.

Gotcha: Telemetry is on by default. If you do not want usage analytics, add --no-telemetry to the args, or set FRAMELINK_TELEMETRY=off in the env block.

Gotcha: The --image-dir flag controls where download_figma_images writes files. If you do not set it, images land in the server's working directory, which may not be your project root. The server prints a warning about this at startup.

Alternatives

1. Figma Dev Mode MCP Server (official) - Figma's own first-party MCP server, bundled with Figma's Dev Mode. Provides similar design-to-code data but requires a paid Figma seat and runs through Figma's infrastructure rather than your local API key. Prefer it if you already pay for Dev Mode and want the vendor-supported path. Prefer Framelink if you want a free, MIT-licensed, self-hosted option that works with any Figma plan.
2. 21st.dev Magic MCP - An MCP server focused on UI component generation. It generates React and Tailwind components from prompts but does not read your Figma files. Use it when you want component scaffolding without a specific design source, not when you need to match an existing Figma layout.
3. Raw Figma REST API - You can call the Figma API directly from a custom MCP server or agent tool. The raw responses are large and verbose, which is exactly the problem Framelink solves with its simplification pipeline. Go this route only if you need data Framelink's extractors strip out.