figma-compaction-mcp

Languages: English | Korean

Current version: 3.0.0

figma-compaction-mcp is an MCP server for Figma-link workflows. It fetches upstream Figma design context internally, prunes it into compact plain-text context, and returns that reduced result to the calling agent instead of the full upstream payload.

What It Is

This project is for teams that want agents to work from Figma node URLs without pushing raw upstream Figma MCP output into the caller model context whenever the bridge can safely handle the request.

The intended flow is simple:

1. A user gives an agent a Figma node URL.
2. The agent calls get_figma_compact_context.
3. This server fetches upstream Figma context internally.
4. The server compacts the upstream result into a small line-based DSL.
5. The agent receives compact implementation context and works from that output.

Why Use It

The main reason to use this server is token reduction without losing implementation-critical facts.

Raw Figma MCP responses can be large enough to consume a meaningful part of the caller model context before implementation even begins. This bridge keeps that upstream payload inside the server whenever possible, compacts it first, and only returns the reduced result to the agent.

• Lower token usage for Figma-link prompts
• Smaller model-context footprint before implementation starts
• Cleaner implementation input for agents
• Less raw upstream noise in caller context
• Traceable output with node ids, typography tokens, asset refs, warnings, and fallback hints
• A built-in fallback path when the bridge cannot safely complete

How It Works

This server sits between your agent and the local Figma Desktop MCP server.

User prompt with Figma link
  -> Agent calls get_figma_compact_context
  -> figma-compaction-mcp connects to local Figma Desktop MCP
  -> get_design_context / get_metadata
  -> internal compaction
  -> compact plain-text context returned to the agent

The public entrypoint is get_figma_compact_context.

• figma_url: required full Figma node URL
• mode: optional compaction mode, one of minimal, balanced, debug
• task: optional intent hint, one of implement, inspect, summarize
• include_assets: optional, default true
• include_text_specs: optional, default true
• include_trace_ids: optional, default true
• include_metadata: optional, default true
• max_output_chars: optional explicit output budget

When the bridge succeeds, it returns compact plain-text context plus structured fields for stats, traceability, warnings, and diagnostics. When the bridge cannot safely fetch or compact the node, it returns a fallback handoff so the agent can continue with standard Figma MCP tools directly.

Example compact output:

src|figma|get_design_context|4:5100|FILE_KEY
sum|Example screen|frame|375x876|535,258
el|4:5107|field_card|w343;layout:column;r20;p:16,20,20,20;bg:#ffffff
tx|4:5106|Section title|t1
ty|t1|Inter|600|20|24|#333333
as|imgAsset|asset|4:5107|asset_slot|/assets/example-image.png

Example URL shape:

https://www.figma.com/design/FILE_KEY/FILE_NAME?node-id=NODE_ID&m=dev

Requirements

To use the Figma-link bridge flow, you need:

• Figma Desktop
• Dev Mode enabled in Figma Desktop
• Desktop MCP server enabled in Figma Desktop
• Node.js 18+

Default upstream Figma MCP endpoint:

http://127.0.0.1:3845/mcp

Override with:

FIGMA_MCP_URL

Installation

Install globally:

npm install -g figma-compaction-mcp

Or run with npx:

npx figma-compaction-mcp

MCP Client Registration

Register this server in your MCP client.

Example using npx:

{
  "mcpServers": {
    "figma-compaction": {
      "command": "npx",
      "args": ["-y", "figma-compaction-mcp"]
    }
  }
}

Example using a global install:

{
  "mcpServers": {
    "figma-compaction": {
      "command": "figma-compaction-mcp",
      "args": []
    }
  }
}

Your client may use JSON, TOML, or another config format, but the command registration model is the same.

How To Use It

1. Open Figma Desktop and enable Dev Mode and the desktop MCP server.
2. Register figma-compaction-mcp in your MCP client.
3. Give your agent a Figma node URL.
4. Have the agent call get_figma_compact_context first.
5. Use the returned compact context for implementation, inspection, or summarization.
6. If the server returns a fallback handoff, continue with the standard Figma MCP tools for the same node.

In practice:

• Small and medium components usually return compact context directly.
• Large screens can still return larger output when the retained structure, text, and assets matter.
• balanced mode is the default for normal implementation work.
• Only set max_output_chars when you intentionally want a hard output budget.

Limitations

• Final tool routing still depends on the MCP host or agent. This server can strongly guide usage, but it cannot forcibly override host-side routing.
• When the bridge cannot safely complete a request, it returns a compact fallback handoff instead of passing raw upstream payloads through this server response.
• Compaction is optimized for implementation relevance, so purely decorative wrappers and chrome-like nodes may be pruned outside inspect-oriented flows.

Other Information

• Release history: CHANGELOG.md
• Compact contract draft: SPEC.md
• Source repository: https://github.com/s9hn/figma-compaction-mcp
• Contributions: issues and pull requests are welcome on GitHub
• Issues: GitHub Issues
• License: MIT