# Figma Codex Bridge

[![CI](https://github.com/xiaobai59/figma-codex-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/xiaobai59/figma-codex-bridge/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-0f766e.svg)](https://modelcontextprotocol.io/)
[![Local first](https://img.shields.io/badge/local--first-127.0.0.1-22c55e.svg)](docs/privacy.md)

[English](README.md) | [简体中文](README.zh-CN.md)

## Select in Figma. Build with Codex.

Give Codex implementation-ready context from the exact Figma frame you are
viewing—without copying a file URL, looking up a node ID, or managing a Figma
API token.

**Current selection · Local authenticated bridge · Read-only tools · Shared by multiple Codex tasks**

![Figma Codex Bridge demo: select a frame in Figma and request a Design Context Pack from Codex](docs/assets/demo.gif)

> Built for Codex and tested with Codex App and CLI. The server uses the
> Model Context Protocol and may work with other stdio MCP clients.

## Why developers use it

| Select what you see | Get context made for implementation | Keep the bridge local |
| --- | --- | --- |
| Read the active Figma Desktop selection directly. No URL or node-ID handoff. | Receive bounded structure, tokens, components, variables, styles, asset candidates, CSS suggestions, and an optional PNG in one call. | The plugin and MCP processes communicate over authenticated `127.0.0.1`; the tool surface is read-only. |

The flagship `figma_get_design_context` tool turns the current selection into
a compact **Design Context Pack** that an implementation agent can use without
first exploring the entire Figma document.

### One Figma connection, multiple Codex tasks

```mermaid
flowchart LR
  A["Codex task A"] --> D["Shared local bridge"]
  B["Codex task B"] --> D
  C["Codex task C"] --> D
  D --> E["Figma Desktop plugin"]
  E --> F["Active file and selection"]
```

Each Codex task may start its own MCP process. Compatible processes validate
the bridge name, version, token, and tool set, then safely share one open Figma
plugin. The automated test suite verifies this multi-process round trip.

## How it is different

| Figma Codex Bridge | Typical API-based workflow |
| --- | --- |
| Uses the file and selection already open in Figma Desktop | Requires a file URL, key, or node ID |
| No Figma REST API token | Requires token creation and management |
| Returns bounded, implementation-oriented context | Often starts from a broad document payload |
| Local loopback bridge protected by a generated token | Usually depends on a remote service |
| Read-only tool surface | May expose canvas-changing operations |

This table describes the workflow this project is designed for; other Figma
tools may offer different capabilities, including write operations.

## 60-second setup

Requirements: Figma Desktop, Node.js 20 or later, and Codex App or CLI.
Figma Web alone cannot run the development plugin.

```bash
git clone https://github.com/xiaobai59/figma-codex-bridge.git
cd figma-codex-bridge
npm run setup
```

The setup command creates a private `.figma-codex-bridge/` directory containing:

- `codex.toml`: an MCP configuration with the absolute server path and a random
  local bridge token
- `plugin/manifest.json`: a generated Figma development plugin using the same
  token

Then:

1. Merge `.figma-codex-bridge/codex.toml` into your Codex configuration.
2. In Figma Desktop, choose **Plugins > Development > Import plugin from
   manifest...** and select `.figma-codex-bridge/plugin/manifest.json`.
3. Restart or reload Codex MCP servers.
4. Run **Figma Codex Bridge** from Figma's Development plugins.
5. Ask Codex to call `figma_status`.

The generated directory contains a local credential and is ignored by Git.
Rotate it at any time:

```bash
npm run setup -- --rotate-token
```

Use a custom port with:

```bash
npm run setup -- --port 39555
```

### Codex CLI alternative

After `npm run setup`, the equivalent CLI form is:

```bash
codex mcp add figma-codex-bridge \
  --env FIGMA_LOCAL_MCP_PORT=38455 \
  --env FIGMA_LOCAL_MCP_TOKEN=<generated-token> \
  -- node /absolute/path/to/figma-codex-bridge/server.mjs
```

Use the token and path generated in `.figma-codex-bridge/codex.toml`; do not
paste a token into an issue or commit it.

## Use it

```text
Read my current Figma selection with figma_get_design_context. Extract the
layout, component hierarchy, typography, colors, spacing and reusable design
tokens, then implement the screen in this repository. Include a screenshot for
visual validation.
```

Recommended flow:

```text
figma_status
  -> figma_get_design_context
  -> implement
  -> figma_get_screenshot for focused visual comparison
```

If nothing is selected, use `figma_get_page_structure` to find the relevant
top-level frame first.

### What Codex receives

```json
{
  "roots": [{ "name": "Introduction Card", "type": "FRAME", "width": 1888, "height": 543 }],
  "tokens": { "colors": [], "spacing": [], "radii": [], "typography": [] },
  "components": [],
  "variables": [],
  "styles": [],
  "assets": [],
  "implementationHints": { "autoLayoutNodes": 2 }
}
```

The actual response includes the bounded node tree and resolved values. See a
[trimmed example](docs/design-context-example.json).

## Tools

| Tool | Purpose |
| --- | --- |
| `figma_status` | Check the connection, active file, page, and selection. |
| `figma_get_design_context` | Build an implementation-ready Design Context Pack. |
| `figma_get_file_metadata` | List file metadata and all pages. |
| `figma_get_page_structure` | Read bounded top-level structure on a page. |
| `figma_get_selection` | Read the current selection and bounded child tree. |
| `figma_get_node` | Read one node by Figma node ID. |
| `figma_get_screenshot` | Export a selected or requested node as PNG. |

Tree tools support `depth`, `maxChildren`, and `maxNodes`. Screenshot exports
are limited by scale, pixel count, and response size. Node IDs accept both
Figma's `2:131` form and the link form `2-131`.

See [the complete tool reference](docs/tool-reference.md) for limits and inputs.

## Privacy and security

- The server listens only on `127.0.0.1`.
- The generated plugin and MCP process share a random bridge token.
- Browser origins are restricted; wildcard CORS is not used.
- Tools are read-only and cannot edit the Figma canvas.
- Figma files and screenshots are not intentionally persisted by the bridge.
- Responses use node, text, body, screenshot, and concurrency limits.

MCP responses can still contain names, copy, layout values, and images from
the active file. That content may be processed by the MCP client and model
provider you configured. Read [the privacy guide](docs/privacy.md) before using
private or regulated designs.

This independent open-source project is not affiliated with Figma or OpenAI.

## Architecture

```mermaid
flowchart LR
  A[Codex or stdio MCP client] -->|MCP| B[Node bridge]
  B -->|Authenticated localhost HTTP| C[Figma Desktop plugin]
  C -->|Read-only Plugin API| D[Active file and selection]
```

One process owns the loopback bridge; additional compatible Codex conversations
forward through that owner, allowing them to share one open Figma plugin
instance. Incompatible versions or tokens fail with an actionable error instead
of silently connecting to the wrong bridge.
See [architecture details](docs/architecture.md).

## Current scope

- Tested client: Codex App and Codex CLI
- Platform requirement: Figma Desktop development plugin
- Tool surface: read-only
- Distribution: GitHub source release; npm publishing is intentionally disabled

## Roadmap

- Component and variable alias resolution
- Exportable asset metadata and code-generation recipes
- Figma-to-local-implementation visual comparison
- Installer packages and verified compatibility guides for more MCP clients
- Optional write tools only with scoped permissions and explicit confirmation

Have a workflow this bridge should support? Open a
[feature request](https://github.com/xiaobai59/figma-codex-bridge/issues/new?template=feature-request.yml)
or start a Discussion. If this makes your Figma-to-Codex workflow smoother,
consider starring the repository—it helps other developers discover it.

## Development

```bash
npm test
npm run check
npm run doctor
```

Loopback integration tests run in GitHub Actions. See [CONTRIBUTING.md](CONTRIBUTING.md),
[SECURITY.md](SECURITY.md), [troubleshooting](docs/troubleshooting.md), and the
[launch kit](docs/launch-kit.md).

## License

[MIT](LICENSE)