# cyber-figma A CLI, a local MCP server, and an agent plugin for the [Figma REST API](https://developers.figma.com/docs/rest-api/) โ€” built for AI-assisted workflows. ๐Ÿ“– **[Documentation](https://cyberuni.github.io/cyber-figma/)** - **CLI** โ€” `cyber-figma ` for terminals, scripts, and agents that shell out. [Jump to CLI โ†’](#cli) - **MCP** โ€” a local stdio server exposing `figma_*` tools. [Jump to MCP โ†’](#mcp-server) - **Plugin** โ€” the published npm package *is* the plugin root. [Jump to plugin โ†’](#agent-plugin) > **Status: scaffolding.** The package is not published to npm yet and no commands or tools > are implemented. What *is* finished is the researched Figma surface the implementation is > built against โ€” see [Research](#research) โ€” and the documentation site covering > authentication, plans, limits, and API coverage. ## Installation ```sh npm install -g cyber-figma ``` Requires Node.js 22 or newer. See the [installation guide](https://cyberuni.github.io/cyber-figma/installation/) for the plugin and MCP paths. ## Authentication ```sh export FIGMA_ACCESS_TOKEN= export FIGMA_TEAM_ID= # optional default team ``` Or pass `--token ` and `--team ` per command. Create a token at **Settings โ†’ Security โ†’ Generate new token** in Figma, choosing scopes at creation time. Figma has three auth modes and they are **not interchangeable** โ€” each reaches a different subset of the API: | | Personal access token | Plan access token | OAuth 2 | | --- | --- | --- | --- | | Header | `X-Figma-Token` | `X-Figma-Token` | `Authorization: Bearer` | | Plan required | none | Organization or Enterprise | none | | Max expiration | 90 days, no rotation | 365 days, refreshable | 90 days, refreshable | | Rate limit counted per | **user** โ€” every script shares one budget | **token** | user, per app | `cyber-figma` defaults to a personal access token because it is the only mode covering the whole surface: plan tokens cannot write comments or variables and cannot call `/v1/me`, and OAuth cannot call the Payments API at all. `FIGMA_TEAM_ID` exists because Figma provides **no way to discover a team ID from a token** โ€” read it from the segment after `/team/` in the team page URL. Two things that reliably surprise people: - **An expired token answers `403`, not `401`.** Do not read `403` as "permission denied" alone. - **A View or Collab seat gets ~6 `GET file` calls per month**, on every plan including Enterprise. Full detail: [Authentication](https://cyberuni.github.io/cyber-figma/authentication/) ยท [Plans and limits](https://cyberuni.github.io/cyber-figma/reference/plans-and-limits/). Keep the token out of `~/.zshrc` โ€” put it in a `0600` file and source that, or read it from a password manager. Shell profiles are world-readable and are the files most likely to end up in a dotfiles repo. ## CLI ```sh cyber-figma [options] ``` Global options: `--token`, `--team`, `--json`, `--toon` (token-efficient [TOON](https://github.com/kunchenguid/axi#the-10-principles) for agents), `--full`. No commands are implemented yet. The planned namespace map and the output, pagination, and error conventions are on the [CLI overview](https://cyberuni.github.io/cyber-figma/cli/). ## MCP server A local **stdio** server, shipped in the same package and calling the same core operations as the CLI. Tools are named `figma__`. ```json { "mcpServers": { "cyber-figma": { "command": "node", "args": ["-e", "import('cyber-figma/mcp')"], "env": { "FIGMA_ACCESS_TOKEN": "" } } } } ``` Set `CYBER_FIGMA_MCP_FORMAT=toon` for token-efficient output. Per-host wiring for Claude Desktop, Claude Code, Cursor, Codex, and the MCP Inspector is on the [MCP page](https://cyberuni.github.io/cyber-figma/mcp/). This is **not** Figma's own MCP server. Figma ships one that handles its own OAuth flow and is limited to clients in the Figma MCP Catalog; this is a local REST API wrapper using REST API credentials. The two can be installed side by side. ## Agent plugin The published npm package **is** the plugin root, so installing the plugin gets the skills, the MCP server, and the CLI at once โ€” no clone to keep in sync. ```sh /plugin marketplace add cyberuni/cyber-figma /plugin install cyber-figma@cyberuni ``` The package ships an [Agent Plugins 1.0.0](https://github.com/agentplugins/agent-plugins-spec) manifest (`plugin.json` / `mcp.json`) alongside per-vendor manifests for Claude Code, Cursor, and Codex. The spec expands only `${PLUGIN_ROOT}` and `${PLUGIN_DATA}`, so the portable `mcp.json` sets no `env` block โ€” a `"${FIGMA_ACCESS_TOKEN}"` value there would reach the server as that literal string and shadow the real token. Export the variables in the environment that launches the agent. ## API coverage The Figma REST API is **53 HTTP operations**: 50 in the OpenAPI spec, plus a Discovery endpoint absent from the spec, plus 2 OAuth token endpoints. Only **11 mutate** โ€” comments, reactions, webhooks, variables, and dev resources. Nothing in the REST API creates or deletes files, projects, teams, pages, or nodes; that lives in the Plugin API. Every endpoint group, its status here, its rate-limit tier, and its plan gate: [API coverage](https://cyberuni.github.io/cyber-figma/reference/api-coverage/). ## Research Figma API facts in this repo are researched, not remembered. Two documents are the source of truth for every claim on the site and in the code: | Document | Covers | | --- | --- | | [`docs/research/figma-rest-api.md`](docs/research/figma-rest-api.md) | Endpoint inventory, response shapes, the four pagination models, known OpenAPI spec defects, documented gaps | | [`docs/research/figma-plans-and-limits.md`](docs/research/figma-plans-and-limits.md) | Plan and seat gating, the 24 OAuth scopes, rate limits, token lifecycle | The full research record โ€” question framing, evidence log with confidence ratings, contradictions, and recheck triggers โ€” lives under [`.research/`](.research/). If a fact you need is missing, add it there with a source link rather than inlining it elsewhere. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup and the in-repo MCP server configuration, and [AGENTS.md](AGENTS.md) for the architecture and conventions AI coding assistants should follow. ```sh pnpm install pnpm verify # lint + build + typecheck + test + knip pnpm web dev # run the documentation site locally ``` ## License [MIT](license)