figma-opencode-mcp

Local-first MCP server for OpenCode/Codex that connects AI coding agents to the currently open Figma file through a local plugin bridge.

No Figma API token required. No Figma REST API in default mode. All communication stays on your machine.

Version: v0.2.2 — fix docs URL in CLI help. Run with a single npx command.

Key Features

• 🔌 No Figma API token required in default mode

• 🔒 No data leaves your machine — local WebSocket bridge

• 📐 Read current selection — get node data from Figma

• 📋 Export selection as JSON — structured data for design-to-code

• ✏️ Create frames and text — basic write operations

• 🔍 Audit selection — design system heuristics (spacing, typography, layout)

• 🧩 Works with OpenCode and Codex via MCP stdio transport

• 📦 Run with a single npx command — no clone or install needed

Related MCP server: figmind

Important Limitations

⚠️ This does not magically access any private Figma file by URL.

• You still need to open the Figma file in Figma.

• You must run the local plugin bridge inside the file.

• The plugin can only access what Figma Plugin API allows in the current file/session.

Architecture

OpenCode/Codex → MCP stdio → WebSocket (127.0.0.1:3845) → Plugin UI → Plugin Main → Figma API

See docs/architecture.md for details.

Quick Start

Option A: Install with npx (recommended)

Run the MCP server directly — no clone or local build needed:

npx -y figma-opencode-mcp@latest

Configure OpenCode/Codex

OpenCode:

opencode mcp add figma-opencode-mcp -- npx -y figma-opencode-mcp@latest

Codex:

codex mcp add figma-opencode-mcp -- npx -y figma-opencode-mcp@latest

.mcp.json (any MCP client):

{
  "mcpServers": {
    "figma-opencode-mcp": {
      "command": "npx",
      "args": ["-y", "figma-opencode-mcp@latest"]
    }
  }
}

Note: The npm/npx command only installs the MCP server. You still need to import and run the Figma plugin separately (see step 4).

Option B: Local clone (for development)

git clone <repo-url> figma-opencode-mcp
cd figma-opencode-mcp
npm install
npm run build

Start MCP Server:

# Development mode (hot reload)
npm run dev

# Production mode
node dist/index.js

Local MCP config:

{
  "mcpServers": {
    "figma-opencode-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/figma-opencode-mcp/dist/index.js"]
    }
  }
}

4. Run Figma Plugin (required for both options)

1. Build the plugin: npm run build:plugin (skip if using npx — download the plugin from releases)

2. In Figma: Plugins → Development → Import plugin from manifest

3. Select plugin/manifest.json

4. Run the plugin in your Figma file

5. The plugin will connect to ws://127.0.0.1:3845

6. Back in OpenCode/Codex, call figma_ping

Tools

See docs/tools.md for detailed documentation.

Example Prompts

Use figma_ping to check connection.
Use figma_get_selection to read my current selected frame.
Use figma_export_selection_json and generate a React/Vite component.
Use figma_audit_selection and suggest design-system improvements.

Project Structure

figma-opencode-mcp/
├── src/                  # MCP server source
│   ├── index.ts          # Entry point
│   ├── mcp/              # MCP layer (server, tools, schemas, handlers)
│   ├── bridge/           # WebSocket bridge (WS server, client, pending requests)
│   └── shared/           # Shared types (protocol, errors, logger, serialize)
├── plugin/               # Figma plugin (manifest, code, UI, types)
├── docs/                 # Documentation
├── examples/             # MCP config examples
├── scripts/              # Dev/build/verify scripts
└── README.md

Security

• No token, no REST API in default mode.

• WebSocket binds only to 127.0.0.1.

• No data sent to external servers.

• No eval or shell execution.

• No .env with secrets.

See docs/security.md.

Roadmap

v0.2.0 ✅

• npm package packaging with npx support

• --version and --help CLI flags

• Plugin packaging (plugin.zip)

• Documentation updates for npx install

v0.3.0

• figma_extract_design_tokens

• figma_generate_react_spec

• figma_compare_code_with_design

• figma_create_component

• figma_apply_auto_layout

• figma_export_svg_png

v0.4.0

• Integration profile for opencode-power-kit

• /figma-setup slash command

• /figma-to-react workflow

• /figma-audit workflow

• figma-design-system skill

v1.0.0

• Stable no-token local bridge

• Better plugin session management

• Better schema docs

License

MIT