figcraft-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
figcraft-mcp-bridge
A Bun + TypeScript MCP bridge that connects OpenCode to
FigCraft Desktop through figcraft-cli mcp --attach <port>. The MCP server key is
figcraft-mcp; this repository is deliberately named differently so it cannot be
confused with the unrelated third-party project of the same name.
The bridge is long-running: it can stay alive while FigCraft is closed and attach
automatically as soon as the control port opens. An agent can even start FigCraft itself
with the figcraft_launch tool, so designing never requires restarting OpenCode.
Table of contents
Related MCP server: Figma Local MCP
Features
Auto-attach to FigCraft when its control port opens (~1.5 s).
Auto-reconnect when FigCraft is closed and reopened.
figcraft_launch— the agent can start FigCraft with its control port itself.figcraft_status— state, port, FigCraft processes, diagnostics, errors, retry count.figcraft_commands— design tool list, or diagnostics when not connected.Port auto-detection from the running process'
--controlflag (FIGCRAFT_PORT=auto).All 19 FigCraft design tools are forwarded as-is (
create_node,batch,screenshot, ...).tools/list_changedis sent to OpenCode, so tools appear/disappear without a restart.Rotating log file.
Requirements
Requirement | Notes |
runs the MCP server | |
FigCraft Desktop >= 0.18.1 | must ship |
OpenCode | with local (stdio) MCP support |
Quick check:
bun --version
figcraft --version
figcraft-cli mcp --help | headIf figcraft-cli is not on PATH, set FIGCRAFT_CLI_PATH to its absolute path
(for example the path inside an AppImage).
Quickstart
1. Clone and install
git clone https://github.com/muhnazih029/figcraft-mcp-bridge.git
cd figcraft-mcp-bridge
bun install
bunx tsc --noEmit2. Register the MCP server in OpenCode
Add this to ~/.config/opencode/opencode.json (or your OpenCode config):
{
"mcp": {
"servers": {
"figcraft-mcp": {
"type": "local",
"command": ["bun", "run", "/ABSOLUTE/PATH/TO/figcraft-mcp-bridge/src/index.ts"],
"environment": { "FIGCRAFT_PORT": "auto" },
"enabled": true
}
}
}
}Replace /ABSOLUTE/PATH/TO/... with the output of pwd from step 1. Restart OpenCode
once after adding this entry.
An example file is available at examples/opencode.json.
3. Make sure FigCraft can start with a control port
FigCraft must be launched with --control <port>. The safest way:
./scripts/install.sh # installs the launcher and the .desktop overrideOr edit the FigCraft .desktop entry manually:
Exec=/path/to/figcraft --control 7979 %UThen run update-desktop-database ~/.local/share/applications.
4. Use it
Open OpenCode and ask for a design. If FigCraft is not running, the agent calls
figcraft_launch; the app starts, the bridge attaches, and the design tools appear.
Alternatively, open FigCraft from your launcher/DMS — the bridge will attach either way.
Architecture and status flow
flowchart LR
OC[OpenCode] -->|stdio JSON-RPC| BR[figcraft-mcp bridge]
BR -->|TCP probe| P{control port}
P -- closed --> W[waiting_for_app]
P -- open --> A[attaching]
A --> CLI[figcraft-cli mcp --attach]
CLI --> APP[FigCraft Desktop]
A --> C[connected + 19 tools]
C -->|tools/list_changed| OC
W -->|figcraft_launch| APPThe bridge keeps its own process alive, so FigCraft can be closed and reopened any number of times without restarting OpenCode.
Tools
Tool | Purpose |
| Full connection status plus diagnostics |
| Design tool list, or hints when not connected |
| Start/reuse FigCraft and attach |
19 design tools | Forwarded from |
The design tools are list_commands, run_command, batch, create_node,
set_properties, inspect_document, get_node, select, export, screenshot,
open_file, save_file, undo, redo, pointer, key, type_text,
inspect_ui, and wait_for_changes.
Status behaviour (why it does not become "connecting")
OpenCode only has two states for a local MCP server: connected and failed.
A server is marked failed when its process exits, and OpenCode never restarts
local processes that died (packages/core/src/mcp/index.ts, stdio.ts).
Pencil appears to "turn into an error and then connect" because its MCP binary lives inside the AppImage mount; when the app closes, the mount disappears, the MCP process dies, and OpenCode marks it failed. Opening the app again makes the binary reappear, but a reload/restart is still normally required to spawn it again.
This bridge deliberately does the opposite: it stays alive when FigCraft closes,
removes the design tools via notifications/tools/list_changed, and exposes
figcraft_status as the diagnostic centre. The result is that you can open and close
FigCraft repeatedly without restarting OpenCode. A fail-fast mode like Pencil's is
possible, but then reopening FigCraft would require an OpenCode restart.
Diagnostics
When the port is closed, the bridge reads /proc/<pid>/cmdline to distinguish three cases:
Condition |
|
FigCraft running without |
|
FigCraft running on another port |
|
No FigCraft process | empty |
With FIGCRAFT_PORT=auto, the port of a running process is adopted automatically.
Logging
tail -f ~/.local/share/figcraft-mcp/bridge.logThe log rotates to bridge.log.1 when it exceeds FIGCRAFT_LOG_MAX_BYTES.
Configuration
Variable | Default | Notes |
|
| the control server must bind to loopback |
|
| use |
|
| absolute paths are allowed |
|
| used by |
|
| |
|
| |
|
| |
|
|
|
|
| before rotating to |
Example with non-standard paths:
"environment": {
"FIGCRAFT_PORT": "auto",
"FIGCRAFT_CLI_PATH": "/opt/figcraft/figcraft-cli",
"FIGCRAFT_APP_PATH": "/opt/figcraft/figcraft"
}Example prompts
Check the FigCraft status first. If it is not connected, open the app, then create a
340x440 profile card with a purple avatar, the name "Nazih", the role "Design Engineer",
and a black CTA button labelled "Let's collaborate →".Inspect the open document, then add a new frame to the right containing three feature
cards with vertical auto-layout, gap 16 and padding 24. Do not touch the existing
portfolio frame.List the available FigCraft commands and explain which ones create components and
variables. Do not modify the document yet.Tip: ask the agent to call figcraft_status before designing so the connection and
document state are clear.
Helper scripts
./scripts/install.sh # check deps, install launcher + .desktop, print config
./scripts/uninstall.sh # remove launcher + .desktop + MCP entry (with .bak backups)
./scripts/uninstall.sh --keep-config # remove files only, keep configuration
./scripts/doctor.sh # check binaries, port, .desktop entry and recent logTry it yourself
Check the environment:
./scripts/doctor.shYou should see
OK figcraft,OK figcraft-cli,OK pid ... --control 7979, andOK port 7979 is reachable.Watch the log in another terminal:
tail -f ~/.local/share/figcraft-mcp/bridge.logIn OpenCode, call
figcraft_status— expectstate: connectedand 19 tools inbackendToolNames.Close FigCraft. The log writes:
state connected -> waiting_for_app (FigCraft Desktop control port closed). The design tools disappear, but MCP does not error.Reopen it in either of two ways:
from chat: call
figcraft_launch— the app starts and attaches in ~1.5 s;from your DMS/launcher: click FigCraft as usual (the
.desktopentry carries--control).
Verify:
figcraft_statusreturnsconnected, and the log showsstate waiting_for_app -> attaching -> connected (19 tools).Optionally test uninstall/reinstall:
./scripts/uninstall.sh ./scripts/install.shRestart OpenCode once, then repeat steps 3-6.
Development
See CONTRIBUTING.md. In short:
bun install
bun run typecheck
bun run test
bun run smoke # works without FigCraft installedGitHub Actions CI runs all four checks on every push and pull request.
License
MIT — see LICENSE.
Security
The FigCraft control port is a loopback TCP socket with no authentication. Any process running as the same user on the same machine can connect and send design commands (read documents, edit layers, export/save files). Never forward this port to a network.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Agent-Native design tool - create and edit visual designs with agent assistance
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables coding agents to interact with the currently open Figma file via local MCP tools, including reading the design, extracting nodes as PNG, React, HTML or CSS, editing the canvas when permitted, and sharing saved component sets.3954 npmMIT
- AlicenseAqualityBmaintenanceEnables an agent to read, edit, and build Figma designs from scratch — including style guides, variables, components, and screens — through a local plugin bridge to the open file's Plugin API, with no Figma token or REST API calls.211MIT
- AlicenseBqualityCmaintenanceDrives a running FigCraft desktop app through its local control channel, letting MCP clients inspect and edit documents, run menu-level commands, and capture screenshots with live UI feedback. It also exposes a Figma-compatible tool surface so existing Figma workflows and prompts can drive FigCraft unchanged.24GPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to control FigCraft Desktop in real time, streaming UI elements with live cursor feedback, auditing designs against Anti-Slop UI rules, and wiring interactive prototype flows.1MIT