Repository: GLips/Figma-Context-MCP

Stars: 14408

CLAUDE.md Copy Chapter

Framelink MCP for Figma

Framelink MCP for Figma is a Model Context Protocol (MCP) server that gives AI coding tools (Cursor, etc.) access to Figma design data. It fetches Figma files/nodes via the Figma API, simplifies the response to include only relevant layout and styling information, and serves it to AI clients.

Build & Development Commands Copy Chapter

pnpm install          # Install dependencies
pnpm build            # Build with tsup (outputs to dist/)
pnpm dev              # Development mode with watch + auto-restart (HTTP)
pnpm dev:cli          # Development mode (stdio)
pnpm test             # Run Vitest tests
pnpm type-check       # TypeScript type checking only
pnpm lint             # ESLint
pnpm format           # Prettier formatting
pnpm inspect          # Run MCP inspector for debugging

Running the Server Copy Section

pnpm start            # HTTP mode (default port 3333)
pnpm start:cli        # stdio mode for MCP clients

Running a Single Test Copy Section

pnpm test -- path/to/test.ts
pnpm test -- --testNamePattern="pattern"

Releasing Copy Section

Releases are automated via release-please. On merge to main, release-please reads conventional commit prefixes (fix:, feat:, feat!:) and maintains a release PR. Merging the release PR publishes to npm via OIDC trusted publishing.

PR Title Convention Copy Section

PRs are squash-merged, so the PR title becomes the commit message that release-please parses. Always use Conventional Commit prefixes in PR titles.

Architecture Copy Chapter

Entry Points Copy Section

- src/bin.ts — CLI entry point, calls startServer()
- src/server.ts — Server initialization, handles stdio vs HTTP mode selection
- src/mcp-server.ts — Library re-exports for external consumers (createServer, startServer, etc.)
- src/index.ts — Library exports (extractors, types)

Transport Modes Copy Section

The server supports two transports (configured in src/server.ts):

- stdio — For direct MCP client integration (activated with --stdio flag or NODE_ENV=cli)
- StreamableHTTP — Stateless HTTP transport at /mcp (also served at /sse for backward compatibility with existing client configs)

Core Data Flow Copy Section

1. MCP Tools (src/mcp/tools/) — Define tool schemas and handlers

- get_figma_data — Fetches and simplifies Figma design data
- download_figma_images — Downloads images from Figma

2. Figma Service (src/services/figma.ts) — API client for Figma REST API

- Handles auth (Personal Access Token or OAuth)
- Methods: getRawFile(), getRawNode(), downloadImages()

3. Extractor System (src/extractors/) — Transforms raw Figma API responses

- design-extractor.ts — Entry point, parses API response and calls extractors
- node-walker.ts — Recursive traversal applying extractors to each node
- built-in.ts — Built-in extractors: layoutExtractor, textExtractor, visualsExtractor, componentExtractor
- Extractors are composable; allExtractors combines all built-ins

4. Transformers (src/transformers/) — Convert specific Figma properties
- layout.ts — Layout/positioning transforms
- style.ts — Visual styling (fills, strokes)
- effects.ts — Effects (shadows, blurs)
- text.ts — Text content and styling
- component.ts — Component metadata

Configuration Copy Section

src/config.ts handles CLI args and environment variables:

- FIGMA_API_KEY or --figma-api-key — Personal Access Token
- FIGMA_OAUTH_TOKEN or --figma-oauth-token — OAuth Bearer token
- PORT or --port — HTTP server port (default: 3333)
- --json — Output JSON instead of YAML
- --skip-image-downloads — Disable image download tool

Path Alias Copy Section

The codebase uses ~/ as an alias for src/ (configured in tsconfig.json and vitest.config.ts).

Philosophy Copy Chapter

From CONTRIBUTING.md — important context for development:

1. Unix Philosophy — Tools should have one job and few arguments. Keep tools simple to avoid confusing LLMs.
2. Focused Scope — The server only handles "ingesting designs for AI consumption." Out of scope: image manipulation, CMS syncing, code generation, third-party integrations.
3. Project-level Config — Options unlikely to change between requests should be CLI arguments, not tool parameters.

Quality Copy Chapter

This codebase will outlive you. Every shortcut becomes someone else's burden. Every hack compounds into technical debt that slows the whole team down.

For each proposed change, examine the existing system and redesign it into the most elegant solution that would have emerged if the change had been a foundational assumption from the start.

You are not just writing code. You are shaping the future of this project. The patterns you establish will be copied. The corners you cut will be cut again.

Fight entropy. Leave the codebase better than you found it.

Comment Policy Copy Chapter

Unacceptable Comments Copy Section

- Comments that repeat what code does
- Commented-out code (delete it)
- Obvious comments ("increment counter")
- Comments instead of good naming

Great Comments Copy Section

- Why this exists — what problem does this solve, why is it valuable
- Why it works this way — important design decisions and their rationale
- Why NOT — approaches you considered and rejected, to prevent re-attempting failed ideas
- Warnings — non-obvious gotchas, ordering dependencies, "this must happen before X"
- Domain bridges — when code implements complex domain logic (finance calculations, protocol specs, algorithms) that can't fully express the underlying concept
- Looks wrong — when code appears unused, redundant, or incorrect but exists for a non-obvious reason (e.g., interface contracts for test implementations, load-bearing side effects)
- Negative space — when code deliberately doesn't handle something and that absence is intentional (e.g., "Does not retry—caller handles backoff" prevents someone from "helpfully" adding retry logic that breaks upstream assumptions)

Testing Philosophy Copy Chapter

Write tests. Not too many. Mostly integration.

- Every test has a cost: maintenance, false positives, slower CI. Tests must earn their place.
- Most features need 2-5 tests. Some need zero.
- Zero tests is valid for: simple CRUD, styling, config changes, framework-convention code, etc.
- Design for testability using "functional core, imperative shell": keep pure business logic separate from code that does IO.

Principles Copy Section

- Test behavior, not implementation. Tests should verify what the code does, not how it does it. Only use methods available on the public interface to verify behavior.
- Don't test what the type system guarantees. If TypeScript enforces it at compile time, a runtime test adds no value.
- Don't test the framework. Don't verify that Express routes, React renders, or ORM queries work — test _your_ logic.
- Prefer real implementations over mocks. Mocks couple tests to implementation details and hide real bugs. Only mock at system boundaries (network, filesystem, time).

Only test behavior where: Copy Section

- A failure would frustrate or block real users
- The behavior is non-obvious and could regress silently
- It's a critical integration point or state transition

Skip testing: Copy Section

- Implementation details, private methods, trivial code
- Edge cases that won't occur in practice
- Variations that test the same underlying behavior

Error Handling Copy Chapter

Trust internal code and framework guarantees. Only validate at system boundaries — user input, external APIs, file I/O. Don't add try/catch, fallbacks, or defensive checks for scenarios that can't happen in practice. Let errors propagate naturally; the caller that knows how to handle them should be the one catching them.

External Libraries Copy Chapter

Use the context7 MCP first to gather information on unfamiliar libraries or APIs. If that fails, you may search the code directly or search the web for more detail.

Communication Style Copy Chapter

When reviewing plans, providing feedback, or analyzing approaches, be genuinely critical. Flag real risks, tradeoffs, and things that will break rather than being agreeable. Grounded, opinionated analysis is more valuable than polite agreement.

README.md Copy Chapter

<a href="https://www.framelink.ai/?utm_source=github&utm_medium=referral&utm_campaign=readme" target="_blank" rel="noopener">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://www.framelink.ai/github/HeaderDark.png" />
<img alt="Framelink" src="https://www.framelink.ai/github/HeaderLight.png" />
</picture>
</a>

<div align="center">
<h1>Framelink MCP for Figma</h1>
<h3>Give your coding agent access to your Figma data.<br/>Implement designs in any framework in one-shot.</h3>
<a href="https://npmcharts.com/compare/figma-developer-mcp?interval=30">
<img alt="weekly downloads" src="https://img.shields.io/npm/dm/figma-developer-mcp.svg">
</a>
<a href="https://github.com/GLips/Figma-Context-MCP/blob/main/LICENSE">
<img alt="MIT License" src="https://img.shields.io/github/license/GLips/Figma-Context-MCP" />
</a>
<a href="https://framelink.ai/discord">
<img alt="Discord" src="https://img.shields.io/discord/1352337336913887343?color=7389D8&label&logo=discord&logoColor=ffffff" />
</a>
<br />
<a href="https://twitter.com/glipsman">
<img alt="Twitter" src="https://img.shields.io/twitter/url?url=https%3A%2F%2Fx.com%2Fglipsman&label=%40glipsman" />
</a>
</div>

<br/>

Give Cursor and other AI-powered coding tools access to your Figma files with this Model Context Protocol server.

When Cursor has access to Figma design data, it's way better at one-shotting designs accurately than alternative approaches like pasting screenshots.

<h3><a href="https://www.framelink.ai/docs/quickstart?utm_source=github&utm_medium=referral&utm_campaign=readme">See quickstart instructions →</a></h3>

Demo Copy Chapter

Watch a demo of building a UI in Cursor with Figma design data


How it works Copy Chapter

1. Open your IDE's chat (e.g. agent mode in Cursor).
2. Paste a link to a Figma file, frame, or group.
3. Ask Cursor to do something with the Figma file—e.g. implement the design.
4. Cursor will fetch the relevant metadata from Figma and use it to write your code.

This MCP server is specifically designed for use with Cursor. Before responding with context from the Figma API, it simplifies and translates the response so only the most relevant layout and styling information is provided to the model.

Reducing the amount of context provided to the model helps make the AI more accurate and the responses more relevant.

Getting Started Copy Chapter

Many code editors and other AI clients use a configuration file to manage MCP servers.

The figma-developer-mcp server can be configured by adding the following to your configuration file.

NOTE: You will need to create a Figma access token to use this server. Instructions on how to create a Figma API access token can be found here.

MacOS / Linux Copy Section

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

Windows Copy Section

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

Or you can set FIGMA_API_KEY and PORT in the env field.

If you need more information on how to configure the Framelink MCP for Figma, see the Framelink docs.

Star History Copy Chapter

<a href="https://star-history.com/#GLips/Figma-Context-MCP"><img src="https://api.star-history.com/svg?repos=GLips/Figma-Context-MCP&type=Date" alt="Star History Chart" width="600" /></a>

Learn More Copy Chapter

The Framelink MCP for Figma is simple but powerful. Get the most out of it by learning more at the Framelink site.