Figma Local MCP Bridge

A VS Code extension for managing the local Figma MCP bridge server: server lifecycle, the Figma dev plugin, MCP tool integration for Copilot, and one-click setup for other AI agents — all without leaving the editor.

This is a from-scratch port of the Figma Local MCP GUI Flutter desktop app, rebuilt around native VS Code UI (activity-bar tree view, status bar, output channels, commands) instead of a standalone window.

Features

• Bridge lifecycle — start/stop/restart the local bridge with a health gate (status flips to Running only after /health returns 200), orphan-kill, multi-window adopt-external, session/uptime in the status bar.

• MCP for Copilot — registers an McpServerDefinitionProvider so agent mode gets the Figma MCP tools natively (VS Code ≥ 1.101).

• Plugin build — builds the Figma development plugin (manifest.json, code.js, ui.html, with the bridge port injected) into an extension-owned folder, ready to import into Figma; rebuilds update it in place and a sidecar .installed.json tracks staleness.

• Connect AI agent… — one command adds the Figma MCP server to other agents. Pick any of them (installed ones are detected and preselected):

  Agent	Config written
  Claude Code	claude mcp add-json --scope user if the CLI is on PATH, else ~/.claude.json
  Gemini CLI	~/.gemini/settings.json
  OpenAI Codex CLI	~/.codex/config.toml (or $CODEX_HOME)
  opencode	~/.config/opencode/opencode.json (%APPDATA%\opencode on Windows)
  Kilo Code / Cline / Roo Code	the extension's settings/*mcp_settings.json in VS Code global storage
  Cursor	~/.cursor/mcp.json
  Windsurf	~/.codeium/windsurf/mcp_config.json
  Claude Desktop	claude_desktop_config.json
  Anything else	"Other agent…" copies a generic mcpServers JSON snippet

  Existing entries and settings are preserved (atomic merge, one-time .bak, chmod 600). Preview AI Agent Config… shows the entry without writing it. When the bridge token is changed or regenerated, connected agents are rewritten automatically (or run Update Connected AI Agents). Agents talk to the bridge that this extension runs, so keep VS Code open while you use them.

• Runtime — seeds from a VSIX-bundled runtime-seed/ built from superdoccimo/figma-mcp-free; stage-and-swap, rollback, force-reinstall; optional on-device Build from source with verification (MCP initialize + /health 401/200) before swap.

• System check — Node runtime (VS Code's built-in one counts), port availability/health, Figma desktop process, plugin installed.

Related MCP server: Figma Bridge MCP

Requirements

• VS Code 1.101+ (native MCP support)

• Figma desktop (to import and run the development plugin)

• No Node.js install needed. The bridge, the Copilot MCP server and the AI agent configs all run on VS Code's own binary via ELECTRON_RUN_AS_NODE. Only Build from source needs a real Node.js ≥ 18, and it offers to download a managed copy if none is found.

Extension Settings

Secrets (pairing password, Figma token) live in VS Code Secret Storage — never in settings or argv.

Commands

Open the Figma MCP activity-bar icon for the dashboard tree (Bridge / MCP / Plugin / Runtime / System). Title-bar and context-menu actions cover start/stop/restart, test connection, build plugin, build from source, rollback, and system check. Palette-visible commands use the Figma MCP: prefix.

Loading the plugin into Figma

Figma desktop does not pick up plugins from a folder — development plugins are imported once by manifest path:

1. Run Build Figma Plugin (Plugin section of the tree, or the Command Palette). It prints the path of the built manifest.json; use Copy manifest path to put it on the clipboard.

2. In Figma desktop: Plugins → Development → Import plugin from manifest… and select that file (in the Linux/macOS file dialog, press Ctrl+L / Cmd+Shift+G and paste the path).

3. Run it from Plugins → Development. Keep the pre-filled bridge URL (http://localhost:<port>) and paste the pairing token (Copy token in the Bridge section of the tree).

4. Later rebuilds (port change, runtime update) overwrite the same folder and keep the manifest id, so Figma picks up the new files without re-importing.

The manifest lists only http://localhost:<port> in devAllowedDomains: Figma rejects IP literals such as 127.0.0.1 there (the plugin then shows "Manifest issue" and won't run). The plugin iframe's CSP is built from that list, so inside Figma the bridge must be addressed as localhost, not 127.0.0.1.

Security notes

• The bridge token is passed only via FIGMA_PLUGIN_BRIDGE_TOKEN (never argv).

• AI agent config files are written with mode 600 on POSIX and contain the bridge token in plaintext by design — don't commit or share them.

• Runtime runtime.json files are SHA-256 verified hard-fail before stage-and-swap.

Development

npm install
npm run watch          # esbuild --watch; or press F5 → Extension Development Host
npm run lint
npm run check-types
npm test               # unit (vitest) + integration (@vscode/test-cli)
npm run sync-runtime   # rebuild runtime-seed/ from superdoccimo/figma-mcp-free
npx @vscode/vsce package

Runtime seed

runtime-seed/ is a committed build artifact (bridge + MCP + plugin + runtime.json). Refresh it with:

npm run sync-runtime
# or pin a ref:
node tool/build-runtime.mjs --ref <sha>

The script downloads upstream source, builds with pnpm, bundles with esbuild (CJS), hard-fails on missing plugin files, writes per-file SHA-256s, and smoke-verifies (MCP initialize + /health 401/200).

License

MIT — see the LICENSE file.