AI-Ready Design System Auditor

Connect your Figma Design System to any MCP-compatible AI IDE for free. The plugin audits your Figma file for hardcoded values and disconnected components, injects structured data, and exposes it as three MCP tools — all without a cloud subscription.

For: Non-Enterprise Figma users who want AI-assisted design system work without paying for Figma's Dev Mode API.

What it does

• Audits your Figma file for hardcoded colors, typography, spacing, and disconnected components
• Injects structured token + component data into the Figma file via pluginData
• Exposes that data to any MCP-compatible AI IDE as three local MCP tools
• No cloud, no subscription — works on the free Figma Starter plan

---

Prerequisites

• Figma Desktop (free Starter plan works)
• Node.js 18 or later
• Any MCP-compatible AI IDE (Cursor, Trae, Claude Desktop, Windsurf, etc.)

---

Step 1 — Install the plugin

Open Figma Desktop, then go to Resources → Plugins and search for "AI-Ready DS Auditor".

Alternatively, find it on the Figma Community page by searching "AI-Ready DS Auditor" (pending).

---

Step 2 — Get a Figma Personal Access Token

1. In Figma, open Account Settings (click your avatar → Settings)
2. Go to Security → Personal access tokens
3. Click Generate new token
4. Set the scope to file_content:read (read-only is sufficient)
5. Copy the token — it starts with figd_

Keep this token; you will need it in the MCP server configuration below.

---

Step 3 — Get your Figma file key

The file key is a unique identifier embedded in the Figma file URL.

Open the file in your browser. The URL follows this pattern:

https://www.figma.com/design/XXXXXXXXXXXX/FileName

The XXXXXXXXXXXX segment is the file key.

Alternative: Run the plugin, go to the "AI Context" tab — the File ID field displays the key after you have run an injection.

---

Step 4 — Run the plugin (audit and inject)

1. Open your Figma file that contains the Design System
2. Open the plugin: Resources → Plugins → AI-Ready DS Auditor
3. Click "Inject / Update" — the plugin scans the file and writes structured data into pluginData
4. The health dashboard shows total tokens, component count, and audit issues found

Status indicators:

• Green checkmark — data is injected and current
• Orange warning — data exists but is out of sync with recent design changes (click "Inject / Update" again after making design changes)

---

Step 5 — Build and configure the MCP server

Clone the repository and build all packages:

git clone https://github.com/YOUR_USERNAME/ai-ready-ds-auditor.git
cd ai-ready-ds-auditor

npm install
npm run build

After the build completes, the MCP server entry point is:

packages/mcp-server/dist/index.js

You will reference this file with an absolute path in your IDE configuration below.

---

Step 6 — Configure your IDE

Works with any IDE that supports the MCP protocol. Below are examples for Cursor and Trae — for other IDEs, refer to their MCP configuration docs and use the same command, args, and env values.

Cursor

Create or edit .cursor/mcp.json in your project directory, or ~/.cursor/mcp.json for a global configuration:

{
  "mcpServers": {
    "ai-ds-auditor": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/packages/mcp-server/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_your_personal_access_token",
        "FIGMA_FILE_KEYS": "YOUR_FIGMA_FILE_KEY"
      }
    }
  }
}

Replace /ABSOLUTE/PATH/TO/ with the full path to your cloned repository.

Example on macOS/Linux:

"args": ["/Users/alice/projects/ai-ready-ds-auditor/packages/mcp-server/dist/index.js"]

Example on Windows:

"args": ["C:/Users/alice/projects/ai-ready-ds-auditor/packages/mcp-server/dist/index.js"]

Multiple Figma files: Separate file keys with commas:

"FIGMA_FILE_KEYS": "KEY1,KEY2,KEY3"

After saving the config, reload the MCP server in Cursor (Cursor → Settings → MCP or use the Command Palette: "Reload MCP Servers").

---

Trae

Open Trae settings and navigate to the MCP Servers section, or create/edit your mcp.json configuration file.

Trae uses an array format for mcpServers, and the command field combines the executable and arguments into a single array:

{
  "mcpServers": [
    {
      "name": "ai-ds-auditor",
      "command": ["node", "/ABSOLUTE/PATH/TO/packages/mcp-server/dist/index.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "figd_your_personal_access_token",
        "FIGMA_FILE_KEYS": "YOUR_FIGMA_FILE_KEY"
      }
    }
  ]
}

Replace /ABSOLUTE/PATH/TO/ with the full path to your cloned repository.

Key differences from Cursor:

• mcpServers is an array ([...]) not an object ({...})
• command is an array containing both the executable and its arguments (["node", "/path/to/index.js"])
• name is a separate string field, not used as the object key

---

Available MCP tools

Once the server is running, your IDE's AI agent can call these three tools.

get_design_tokens

Returns design tokens (colors, typography, spacing) formatted for your CSS framework.

Parameters:

• fileKey (optional) — which Figma file to query; defaults to the first file in FIGMA_FILE_KEYS
• framework (optional) — output format: "tailwind" | "css-variables" | "css-modules" | "styled-components"; defaults to "css-variables"

Example prompt:

"Show me all the design tokens as a Tailwind config"

The agent calls get_design_tokens with framework: "tailwind" and returns a theme.extend object with colors, font sizes, and spacing values.

---

get_component_specs

Returns the full specification for a component by name or ID.

Parameters:

• componentName (optional) — search by component name (case-insensitive partial match)
• componentId (optional) — look up by Figma node ID
• fileKey (optional) — which file to query

Example prompt:

"What props does the Button component have?"

The agent calls get_component_specs with componentName: "Button" and returns the component name, description, variants, and usage notes.

---

get_audit_summary

Returns audit issues filtered by category.

Parameters:

• fileKey (optional) — which file to query
• category (optional) — filter by issue type: "color" | "typography" | "spacing" | "component"

Example prompt:

"What are the hardcoded color issues in this design system?"

The agent calls get_audit_summary with category: "color" and returns a list of nodes using hardcoded fill or stroke values instead of color variables, including node IDs and suggested fixes.

---

Figma API rate limits

The free Figma Starter plan allows 6 GET requests per month per file to the Figma REST API.

The MCP server fetches each file once per server session and caches the result in memory. Subsequent tool calls within the same session do not make additional API requests.

To avoid exhausting your monthly quota:

• Keep the MCP server process running rather than restarting it repeatedly
• Each new server start consumes one API call per configured file
• If you do hit the monthly limit, the server returns a clear error message; wait until the next calendar month or upgrade to Figma Professional

---

Troubleshooting

403 Forbidden error from the MCP server

The Figma file must be set to public read access. In Figma, click Share, then change the link permission to "Anyone with the link can view".

"Out of sync" indicator in the plugin

Design changes were made after the last injection. Click "Inject / Update" in the plugin to update the pluginData.

"No data found" from the MCP server

The MCP server reads data written by the plugin. If you have not run "Inject / Update" yet, no data exists for the server to read. Run the plugin first, then retry the tool call.

Token data is empty after restarting the IDE

The MCP server's in-memory cache is session-scoped. Each new server session makes a fresh API call to Figma. This is expected behavior and does not indicate a problem; the cache refills automatically on the first tool call.

Rate limit error (monthly quota exhausted)

The Figma free plan allows 6 REST API calls per month per file. The server will return a descriptive error if this limit is reached. Wait until the next calendar month, or avoid restarting the server unnecessarily (see the rate limits section above).

Wrong absolute path in IDE config

The args path (Cursor) or command array path (Trae) must be an absolute path to packages/mcp-server/dist/index.js. If the path contains spaces, ensure it is properly quoted. Verify the path exists by running node /path/to/packages/mcp-server/dist/index.js in a terminal — it should start and wait for input.

---

Development

npm run dev        # Watch mode for all packages
npm run build      # Build all packages
npm run type-check # TypeScript check across all packages (zero errors required)
npm run lint       # ESLint across all packages (zero errors required)
npm test           # Vitest unit tests

Project structure:

packages/
  plugin/       — Figma plugin (TypeScript + React + Vite)
  mcp-server/   — Local MCP server (Node.js + TypeScript)
  shared/       — Shared types and utilities

---

How the pipeline works

Figma file
    |
    v
[Plugin: Audit & Inject]
    Scans components, tokens, variables
    Finds hardcoded colors / typography / spacing / disconnected layers
    Writes chunked JSON to Figma pluginData
    |
    v
Figma REST API (one call per session)
    |
    v
[MCP Server: local process]
    Reads pluginData chunks via REST
    Reconstructs and caches in memory
    Exposes get_design_tokens / get_component_specs / get_audit_summary
    |
    v
Cursor / Trae AI agent
    Calls tools by name
    Receives formatted token output, component specs, or audit issues

---

License

MIT