@particlesui/mcp-server

The official Model Context Protocol server for Particles UI. It exposes your design tokens, change-impact analysis, accessibility contrast, named themes, and Figma component graphs to AI agents (Claude, Cursor, and any MCP-compatible client) — straight from the source of truth, so your tools reason about real tokens instead of pasted hex codes.

It's read-only: it queries the Particles backend over its REST API and never mutates your tokens.

Requirements

• Node.js ≥ 18
• A Particles account on the Team plan or above — MCP access is enforced server-side. Calls from a lower plan return a clear "upgrade required" error.
• A device-auth token (see Authentication).

Install

npm install -g @particlesui/mcp-server

Installing globally lets your MCP client launch it by an absolute path, which is the most reliable setup (see the Connection closed note). The package provides a particles-mcp binary that speaks MCP over stdio.

Authentication

The server authenticates with a device-auth token, resolved in this order:

1. PARTICLES_TOKEN environment variable — required for headless / CI runs.
2. particles login — if you've signed in with the Particles CLI, the server automatically reads the saved token, so no env var is needed. An expired saved token is ignored (you'll be prompted to log in again).

npm install -g @particlesui/cli
particles login           # device-auth flow; saves your token

particles login saves your token only — it does not store a default project. Set PARTICLES_PROJECT_ID yourself, or let the agent call the list_projects tool.

Configuration

| Variable | Required | Default | Description | | --- | --- | --- | --- | | PARTICLES_TOKEN | Optional¹ | — | Device-auth token. ¹Optional if you've run particles login; required for headless / CI. | | PARTICLES_PROJECT_ID | Optional | — | Default project id used when a tool call omits projectId. Otherwise pass projectId per call (use list_projects to find one). | | PARTICLES_API_BASE | Optional | https://api.particles-ui.com | Backend base URL. |

Set up your client (automatic — recommended)

The server can write the config for you. It uses absolute paths to the exact node and server file, so the Connection closed PATH problem can't happen:

particles-mcp setup                                  # auto-detects installed clients (Cursor / Claude)
particles-mcp setup --client cursor --project <id>   # target one client + set a default project
particles-mcp setup --print                          # just print the JSON snippet, don't write

It merges into your existing config (preserving other servers) and backs up the file first. Then fully quit and reopen your client — MCP servers are spawned per session, so a reload isn't enough. The tools appear under particles-ui.

Flags: --client cursor|claude|claude-code|all, --project <id>, --token <token>, --api-base <url>, --print.

Manual config (reference)

If you'd rather edit by hand: Claude Desktop (claude_desktop_config.json), Claude Code (~/.claude.json), and Cursor (~/.cursor/mcp.json) all use the same shape. Use absolute paths (see the Connection closed note):

{
  "mcpServers": {
    "particles-ui": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/global/node_modules/@particlesui/mcp-server/dist/index.js"],
      "env": { "PARTICLES_PROJECT_ID": "<your project id>" }
    }
  }
}

Find the two absolute paths with which node and echo "$(npm root -g)/@particlesui/mcp-server/dist/index.js".

Tools

| Tool | What it does | | --- | --- | | get_token | Get a token by name — resolved value, CSS variable, tier, and which Figma components use it. | | find_tokens | Natural-language token search (e.g. "a calm background for cards"), ranked by relevance.² | | get_impact | Blast radius of changing a token — affected tokens, the Figma components that bind it, and accessibility risk. | | check_contrast | WCAG contrast ratio between two tokens (AA / AA-large / AAA). | | resolve_theme | A token's resolved value within a named theme (e.g. dark mode). | | get_component_graph | The full token-binding graph for a Figma component — part tree, every property→token binding, gaps, and stale bindings. | | get_component_tokens | Flat list of the tokens a component binds, with per-property confidence. | | list_components | All Figma components that bind tokens, with variants, token counts, and average confidence. | | list_projects | Discover your projects (and their ids). | | list_branches | A project's branches (id, name, whether main). | | list_themes | A project's named themes (id, name). |

² find_tokens uses semantic ranking when embeddings are available for your project, and otherwise falls back to text matching. Embeddings are managed on the Particles side — nothing to configure here.

The component-graph tools read data the Particles Figma plugin produces by analyzing components; analysis itself isn't an MCP tool (it needs the Figma canvas).

Verify it works

Drive the server by hand with the official MCP Inspector before wiring it into a client (after particles login):

npx @modelcontextprotocol/inspector \
  node "$(npm root -g)/@particlesui/mcp-server/dist/index.js"

It opens a UI where you can list the tools and call them against your real tokens.

Troubleshooting

• MCP error -32000: Connection closed — your client couldn't launch the command. This is almost always a PATH problem: apps launched from the dock don't inherit your shell's PATH, so a bare "command": "node" / "npx" can't be found (common with nvm / fnm / Homebrew). Use absolute paths to both node and the installed dist/index.js, as shown above. Avoid pointing command at npx or the particles-mcp bin — both rely on node being on PATH.
• No Particles credentials found — run particles login, or set PARTICLES_TOKEN.
• Authentication failed (401) — the token is missing or expired; run particles login again or refresh PARTICLES_TOKEN.
• requires the Team plan or above — the project's organization is below Team; MCP access is gated.
• find_tokens returns only text matches — semantic embeddings aren't available for that project/branch yet; results still work, just lexically.
• Tools don't appear — confirm a valid token, then fully quit and reopen the client (not just reload).

License

See particles-ui.com for terms.