Figma MCP Setup

Figma MCP setup for DeepSeek Harness

Two independent routes. Pick one; running both registers duplicate Figma tools.

Choose A for a fast read-only setup. Choose B if A returns 403 File not exportable, or if you want the richer tool set (design context, screenshots, variables, code connect).

Route B needs a plugin that the in-box harness does not ship. The assets/ bundle contains it; see step B2.

Before starting

Gather these facts first; every later step depends on them:

1. The harness install path. Where dsh actually runs from:

   which dsh; readlink -f "$(which dsh)"
   

2. The harness home. echo $DSH_HOME (default ~/.dsh).
3. The profile to modify. Usually web. Confirm it exists:

   ls "$DSH_HOME/profiles/"
   

4. Whether a GUI is running. Config changes need a restart; see "Restart" below.

Every command below uses $DSH_HOME and $PROFILE; set them once:

export DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
export PROFILE=web

Route A — PAT + stdio (quick read access)

A1. Get a token

Figma → Settings → Security → Personal access tokens → generate. Scope needed: File content → Read only. Token looks like figd_....

Verify it before wiring anything (a bad token here is much cheaper to find now):

curl -s -H "X-Figma-Token: $FIGMA_TOKEN" https://api.figma.com/v1/me

Expect JSON with your handle/email. A 403 Invalid scope means the token lacks file_content:read; regenerate it.

A2. Install the server into the profile

dsh plugin --profile "$PROFILE" add figma-developer-mcp

The warning declares no dsh.bundle — installed as a plain dependency is expected and correct: this is an MCP server, not a harness bundle. Wiring it up is step A3.

A3. Wire it into the profile patch

Append to $DSH_HOME/profiles/$PROFILE/cordis.patch.yml (top-level YAML array):

- insert:
    - id: mcp-figma
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: figma
        transport: stdio
        command: node
        args:
          - !!js process.env.DSH_HOME + '/profiles/web/node_modules/figma-developer-mcp/dist/bin.js'
          - '--stdio'
        env:
          FIGMA_API_KEY: !!js process.env.FIGMA_API_KEY
          IMAGE_DIR: !!js process.env.DSH_HOME + '/figma-assets'
          FRAMELINK_TELEMETRY: 'off'
        toolCallTimeoutMs: 120000

Adjust /profiles/web/ if $PROFILE is not web.

Two deliberate choices: IMAGE_DIR keeps downloaded assets in one place (otherwise they scatter into the server's inherited cwd), and FRAMELINK_TELEMETRY: 'off' stops the third-party server reporting usage.

A4. Store the token

Write $DSH_HOME/.env (this file does not travel with a repository, which is why it is the right home for a secret):

printf 'FIGMA_API_KEY=%s\n' "$FIGMA_TOKEN" > "$DSH_HOME/.env"
chmod 600 "$DSH_HOME/.env"

The harness loads this file at startup. FIGMA_API_KEY is not a bootstrap-only name, so it is accepted here.

Then restart (see "Restart") and verify with "Verifying" below.

Route B — OAuth + official remote server

B1. Understand why the in-box plugin cannot do this

The shipped @deepseek-ai/dsh-mcp-client builds its Streamable HTTP transport with static headers only — no authProvider, no OAuth code. Servers that demand an authorization-code flow cannot be reached, and no header configuration fixes it: the flow needs a browser round-trip, a PKCE verifier, and token refresh.

Do not try to patch the installed package: $DSH_HOME/profiles/node_modules/* are symlinks into the harness install, so edits are lost on update. Ship a separate plugin instead (supplied in assets/dsh-mcp-oauth).

B2. Install the plugin

Copy assets/dsh-mcp-oauth/ from this skill to a permanent location, e.g. ~/dsh-mcp-oauth. It must not live in a temp directory.

Link the two packages it imports, resolved from the profile's dependency tree:

PLUGIN=~/dsh-mcp-oauth
mkdir -p "$PLUGIN/node_modules/@modelcontextprotocol" "$PLUGIN/node_modules/@deepseek-ai"
ln -sfn "$DSH_HOME/profiles/node_modules/@modelcontextprotocol/sdk"      "$PLUGIN/node_modules/@modelcontextprotocol/sdk"
ln -sfn "$DSH_HOME/profiles/node_modules/@deepseek-ai/schemastery"       "$PLUGIN/node_modules/@deepseek-ai/schemastery"
node -e "import('$PLUGIN/src/index.js').then(()=>console.log('plugin loads OK'))"

If that prints a load error, the symlinks are wrong — fix them before continuing.

B3. Wire it into the profile patch

- insert:
    - id: mcp-figma-remote
      name: '/absolute/path/to/dsh-mcp-oauth/src/index.js'
      config:
        transport: streamable-http
        serverName: figmaRemote
        url: 'https://mcp.figma.com/mcp'
        clientName: 'Claude Code'
        scopes: ['mcp:connect']
        toolCallTimeoutMs: 120000
        failOnStartupError: false

clientName is not cosmetic — Figma allowlists it exactly (see references/figma-gotchas.md). Leave it as Claude Code unless Figma changes its policy.

If you also configured route A, set disabled: true on that row to avoid registering two near-identical sets of Figma tools.

B4. Authorize

Restart, then trigger the first connection (open a session and ask it to do anything; the plugin connects at startup). The plugin prints a consent URL and waits up to 5 minutes:

mcp-oauth(figmaRemote): authorization required — open this URL to grant access:
  https://www.figma.com/oauth/mcp?...

Open it, click Allow. The browser redirects to 127.0.0.1:33418/callback and shows "Authorization complete". Tokens are then cached at $DSH_HOME/mcp-oauth/figmaRemote.json, so this happens once, not per start.

Verifying the install

Do not declare success from a config dump — call a real tool and read real data.

Check the tools are registered. In a session, the model should see mcp__figma__* (route A) or mcp__figmaRemote__* (route B).

Route A:

mcp__figma__get_figma_data with fileKey <key>

Route B — strongest check, because it exercises auth end to end:

mcp__figmaRemote__whoami

This returns your handle, email, and plan — proof the OAuth token is live.

Then read a real node:

mcp__figmaRemote__get_metadata with fileKey <key>, nodeId <id>

The fileKey is the path segment after /design/ in a Figma URL; nodeId comes from ?node-id=2048-42655 (note: URL uses -, tools accept either).

Use a negative control. A tool call that "succeeds" against a bogus key may never have reached the network. Confirm the call really hits Figma by checking that an intentionally bad input produces a server error (a well-formed but nonexistent key should give 404 Not found from Figma, not a local validation message).

Restarting

cordis.patch.yml changes hot-reload under patchReload: live only when the watcher is running; plugin source changes never hot-reload. Environment variables (FIGMA_API_KEY) are read once at process start.

Restart the harness GUI after any config, plugin, or credential change. If the figma tools are missing right after a config edit, restart before debugging.

Troubleshooting

Work through these in order; each is a real failure observed during development.

More detail, including the measurements behind each row: references/figma-gotchas.md.

Bundle contents

Security notes

• Never commit a PAT or a token cache. $DSH_HOME/.env and $DSH_HOME/mcp-oauth/*.json are written 0600; keep them that way.
• A PAT pasted into a chat or log should be treated as compromised — rotate it.
• The OAuth callback listener binds loopback only, so the authorization code is never reachable off-box.
• Route B identifies the client to Figma as Claude Code. If that is unacceptable, use route A — but note it cannot read export-restricted files.