Skip to main content
Glama
dsh-figma-mcp

dsh-figma-mcp

by yoobinkim541
README.md
# dsh-figma-mcp

Figma MCP over **stdio**, for DeepSeek Harness and any other MCP client.

| | |
|---|---|
| Upstream | `https://mcp.figma.com/mcp` (official Figma MCP, streamable HTTP) |
| Downstream | stdio, MCP `2025-06-18` |
| Tools exposed | 47 — Figma's list, unmodified schemas |
| LLM turns per call | **0** — the bridge talks HTTP directly |
| Credentials | reused from the host that already authorized Figma |

---

## Why this exists

DSH's `@deepseek-ai/dsh-mcp-client` speaks `stdio` and `streamable-http` with a **static** header set. Figma's MCP needs an OAuth bearer token that expires, and a proxy cannot mint one:

```console
$ curl -X POST https://api.figma.com/v1/oauth/mcp/register -d '…'
Forbidden                                    # HTTP 403 — no dynamic client registration

$ curl -X POST https://api.figma.com/v1/oauth/token \
    -d 'grant_type=refresh_token&refresh_token=…&client_id=…'
{"error":"Client ID and client secret are required"}   # no secret to send
```

Both were measured against the live service. A `refresh_token` grant with a bare `client_id` is refused, and the registration endpoint is closed, so a new client cannot bootstrap itself. The only working path is to **reuse the credential an already-authorized client stored** — which is exactly what this bridge does, then republishes Figma's tools over stdio with a token it can refresh-by-reconnect.

The alternative in most setups is pointing an agent CLI at Figma and paying a model turn per call. Here a `use_figma` push costs zero tokens.

## Install

```bash
git clone https://github.com/yoobinkim541/dsh-figma-mcp.git
cd dsh-figma-mcp
npm install
node bin/dsh-figma-mcp.js doctor
```

`doctor` prints every credential it can see and then calls `whoami` upstream:

```console
credentials
  keyring:Codex MCP Credentials/Figma|d39d3b62 access=figu… refresh=yes expires in 90d client=pADEsf…

upstream https://mcp.figma.com/mcp
  ok: 47 tools, user yoobin kim
```

No build step. No native compilation — the keyring binding ships prebuilt binaries for Linux, macOS and Windows.

## Getting a credential

The bridge reads, in order:

1. `DSH_FIGMA_TOKEN` (or `FIGMA_MCP_TOKEN`) — an access token, for CI.
2. `~/.dsh-figma-mcp/credentials.json` — written by `dsh-figma-mcp login`.
3. The OS keyring entry `Codex MCP Credentials` / `Figma|*` — what `codex mcp login Figma` writes.
4. `~/.claude/.credentials.json` and `~/.claude.json` — Claude Code / desktop `mcpOAuth` entries.

Any one is enough. The most common setup is to authorize Figma **once** in a host that stores an OAuth token:

```bash
codex mcp login Figma     # once; the bridge then reuses that credential
```

If you already have a token, store it directly and skip the keyring entirely:

```bash
DSH_FIGMA_TOKEN=figu_… node bin/dsh-figma-mcp.js login
```

`login` verifies the token against the live server **before** writing it, so a stored credential is never one that fails at the first call.

Discovery is read-only: it never writes into another tool's store.

## Connect to DeepSeek Harness

Append to `~/.dsh/cordis.patch.yml` (all profiles) or `~/.dsh/profiles/<name>/cordis.patch.yml`:

```yaml
- insert:
    - id: figma-mcp
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: figma
        transport: stdio
        # Absolute path: DSH scrubs the ambient environment, so a bare `node`
        # from a version manager may not resolve.
        command: /usr/bin/node
        args:
          - /absolute/path/to/dsh-figma-mcp/bin/dsh-figma-mcp.js
        toolCallTimeoutMs: 120000
        failOnStartupError: true
```

Restart the harness. Each Figma tool appears as `mcp__figma__<tool>`:

```console
$ dsh headless "Call mcp__figma__whoami and report the handle."
- Handle: yoobin kim  ·  Plan: … (student, Full seat, admin)
```

Two configuration notes that cost real debugging time:

- **`failOnStartupError: true`** — without it a credential problem leaves the harness running with *zero* Figma tools and no error in the tool list. The model then reports "no Figma MCP server is connected", which is technically true but hides the cause.
- **No `env:` block** — `dsh-mcp-client` validates `env` values as strings, and `!!js … || undefined` produces `undefined`, which fails schema validation at load. Credentials come from discovery, so the block is unnecessary.

### Other MCP clients

The bridge is a plain stdio server, so the same command works anywhere:

```jsonc
// Claude Code / Claude Desktop ~/.claude.json
{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["/absolute/path/to/dsh-figma-mcp/bin/dsh-figma-mcp.js"]
    }
  }
}
```

```toml
# Codex ~/.codex/config.toml
[mcp_servers.figma]
command = "node"
args = ["/absolute/path/to/dsh-figma-mcp/bin/dsh-figma-mcp.js"]
```

## CLI

```
dsh-figma-mcp           run the stdio bridge
dsh-figma-mcp doctor    credentials + upstream reachability
dsh-figma-mcp tools     print the 47 upstream tool names
dsh-figma-mcp login     verify and store a token
```

| Variable | Meaning |
|---|---|
| `DSH_FIGMA_TOKEN` / `FIGMA_MCP_TOKEN` | access token; overrides discovery |
| `DSH_FIGMA_REFRESH_TOKEN` | optional refresh token to pair with it |
| `DSH_FIGMA_URL` | upstream URL (default `https://mcp.figma.com/mcp`) |
| `DSH_FIGMA_CREDENTIALS` | where `login` writes |
| `DSH_FIGMA_CODEX_CREDENTIALS` / `DSH_FIGMA_CLAUDE_CREDENTIALS` | extra discovery paths |

## How it works

```
MCP client ──stdio──▶ dsh-figma-mcp ──HTTPS+Bearer──▶ mcp.figma.com/mcp
                       │
                       ├── credentials.js  discover + normalize every store
                       ├── upstream.js     connect, list, call, reconnect on 401
                       └── server.js       expose tools verbatim + provenance
```

Three behaviours are deliberate:

**Tool schemas pass through untouched.** Only a one-line provenance prefix is added to each description. Rewriting `use_figma`'s arguments would break the Figma plugin-API contract, and the `nodeId` strings the rest of the tool set expects are exact.

**A 401 reconnects once, then retries.** The SDK's streamable transport takes a static `requestInit`, so there is no per-request hook to refresh mid-flight; reconnecting with a freshly discovered credential is the equivalent. The retry is safe because an auth failure means the request never reached a tool.

**Errors surface as MCP errors.** A failed call throws with a hint; nothing is turned into a silent empty result, which would look to the model like a tool that succeeded with no output.

## Limitations

- **No dynamic registration.** `POST /v1/oauth/mcp/register` is 403, so `login` needs a token you already obtained. There is no browser-based "click to authorize" flow in this package.
- **Token lifetime is the host's.** With a token from `codex mcp login Figma`, the bridge inherits its ~90-day lifetime. When it expires, re-authorize in that host; the bridge picks up the new value on the next start.
- **`refresh_token` is unused.** Figma requires a client secret alongside it, and no supported store keeps one. A `refreshToken` is carried through `normalize()` for future use but never spent.
- **Resources and prompts are empty.** Figma exposes tools only; those two namespaces answer with empty lists.
- **Linux keyring needs a running Secret Service.** On a headless box use `DSH_FIGMA_TOKEN`; `doctor` says so when discovery comes up empty.

## Tests

```bash
npm test                        # 10 checks: normalization, auth detection, stdio handshake
DSH_FIGMA_SKIP_LIVE=1 npm test  # skip the live handshake (no network / no credential)
```

The live check spawns the real binary over stdio and asserts the `initialize` handshake, so a broken entry point fails the suite rather than shipping.

## Upstream

DeepSeek Harness does not accept external pull requests at the moment (`CONTRIBUTING.md`: *"we cannot accept external pull requests at the moment"*). The supported route is the ecosystem: this repository is tagged **`dsh-plugin`** so it is discoverable, and the harness README's own guidance is to treat the official repo as a source of inspiration rather than a gate.

If the upstream policy changes, `src/` is dependency-light and framework-agnostic; `server.js` is ~120 lines over the MCP SDK.

## License

MIT