# Figma Comments MCP

[![CI](https://github.com/RussGallaway/figma-comments-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/RussGallaway/figma-comments-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A small local TypeScript MCP server for Figma comment threads and reactions. Run it alongside the official Figma MCP: this server handles feedback, while the official server supplies design context, screenshots, nodes, and frames. Built for the RankerAMG workflow, and usable with any accessible Figma file. No project-specific runtime dependency is required. This is an independent project, not an official Figma product.

## Prerequisites

- Node.js 22.19 or newer and npm.
- Access to the Figma files you want to read or comment on.
- Your own Figma personal access token (PAT).
- An MCP client such as Codex.

## Authentication

Each coworker should use their own token. Comments and reactions are attributed to the token owner, and Figma enforces that owner's permissions. OAuth is unnecessary for this initial local server; a hosted multi-user service would need a separate OAuth design.

In Figma, open account **Settings → Security → Personal access tokens → Generate new token**. Choose an expiration and these scopes:

- `file_comments:read`
- `file_comments:write`

Copy the token into your environment or a private local `.env` file. Never commit or share it. Token expiration and revocation are managed in Figma. See [Figma PAT documentation](https://developers.figma.com/docs/rest-api/personal-access-tokens/) and [scope documentation](https://developers.figma.com/docs/rest-api/scopes/).

The server reads only `FIGMA_ACCESS_TOKEN` from its process environment and sends it in `X-Figma-Token`. It checks that the value is present; the first API request validates actual validity, scopes, and file permissions. No live authentication request occurs during startup. It never prints the token.

For a local file:

```sh
cp .env.example .env
chmod 600 .env
```

Edit `.env` locally and set `FIGMA_ACCESS_TOKEN` to your PAT. The file is gitignored and excluded from the package. Node's native env-file launcher loads it into the environment; the server does not search other repositories for credentials. An inherited environment variable takes precedence over the file.

## Build and install

Clone the public repository and install from a built package:

```sh
git clone https://github.com/RussGallaway/figma-comments-mcp.git
cd figma-comments-mcp
npm ci
npm run check
npm run format:check
npm pack
npm install --global ./figma-comments-mcp-0.1.0.tgz
figma-comments-mcp --help
```

Other users can also install the generated `.tgz` directly with `npm install --global /absolute/path/figma-comments-mcp-0.1.0.tgz`. Each person supplies their own credentials afterward. The global installation makes the command available; it does not register the server in your MCP client. This package has not been published to npm; do not assume its name can be installed from the public registry.

Run from source after building:

```sh
node --env-file=.env dist/index.js
```

Or run the globally installed CLI using an existing `FIGMA_ACCESS_TOKEN` environment variable:

```sh
figma-comments-mcp
```

The server uses stdio, so it normally waits for an MCP client rather than showing an interactive prompt. Stdout contains MCP protocol only.

## Codex configuration

Register once in `~/.codex/config.toml` for use across repositories, or in a trusted project's `.codex/config.toml` for project scope. Keep the official Figma server configured separately. See [official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

For an environment token and a globally installed CLI:

```toml
[mcp_servers.figma_comments]
command = "figma-comments-mcp"
env_vars = ["FIGMA_ACCESS_TOKEN"]
enabled = false
```

For desktop clients and a local env file, use absolute paths to Node and the installed script. Find the paths with `command -v node` and `npm root --global`, then substitute your values below. Node flags precede the script:

```toml
[mcp_servers.figma_comments]
command = "/absolute/path/to/node"
args = [
  "--env-file-if-exists=/absolute/private/path/figma-comments.env",
  "/absolute/npm/global/root/figma-comments-mcp/dist/index.js"
]
env_vars = ["FIGMA_ACCESS_TOKEN"]
enabled = false
```

The optional env-file flag allows registration before you create your token file. Enabling without credentials gives a concise startup error. A shell export may not reach an already running desktop app; the absolute env-file launcher avoids depending on that behavior.

Enable for a single **CLI invocation**:

```sh
codex -c 'mcp_servers.figma_comments.enabled=true'
```

Disable for a single invocation if your saved default later becomes enabled:

```sh
codex -c 'mcp_servers.figma_comments.enabled=false'
```

The override applies to that invocation and does not change saved configuration. In desktop settings you can change server enablement and restart the MCP connection; do not assume this is a conversation-only toggle. `codex mcp list` shows registration; `/mcp` shows active connections. [CLI configuration overrides](https://learn.chatgpt.com/docs/developer-commands?surface=cli).

## Tools and examples

| Tool                       | Purpose                                     | Side effect                                  |
| -------------------------- | ------------------------------------------- | -------------------------------------------- |
| `figma_list_comments`      | List and filter grouped threads             | Read only                                    |
| `figma_get_comment_thread` | Read a root and its chronological replies   | Read only                                    |
| `figma_post_comment`       | Create an optional pinned top-level comment | Publishes a comment                          |
| `figma_reply_to_comment`   | Reply to a root thread                      | Publishes a reply                            |
| `figma_delete_comment`     | Delete an explicit comment ID               | Permanent deletion; root may remove replies  |
| `figma_delete_comments`    | Delete up to 100 explicit IDs               | Permanent deletion; partial results reported |
| `figma_add_reaction`       | Add your reaction                           | Writes a reaction                            |
| `figma_delete_reaction`    | Remove your reaction                        | Removes a reaction                           |

Example file keys, node IDs, and comment IDs below are placeholders; substitute values from your own file.

Every tool accepts `file` as a raw Figma file/branch key or an HTTPS Figma URL. Branch URLs select the branch key. IDs remain strings. Inputs reject unknown properties.

### Read threads

```json
{
  "tool": "figma_list_comments",
  "arguments": {
    "file": "https://www.figma.com/design/ExampleFileKey123/RankerAMG",
    "status": "unresolved",
    "includeReplies": true
  }
}
```

`status` defaults to `all`; `resolved` and `unresolved` filter by the root's resolution timestamp. `topLevelOnly: true` omits replies. Explicitly requesting both `topLevelOnly: true` and `includeReplies: true` is rejected. Omitted replies are indicated by `repliesIncluded` and `replyCount`, rather than being presented as nonexistent.

```json
{
  "tool": "figma_get_comment_thread",
  "arguments": { "file": "ExampleFileKey123", "commentId": "123456789" }
}
```

A root ID or reply ID returns the root and all replies in chronological order. Thread results preserve author, reaction, timestamp, resolution, UI order, and client-position metadata. Unexpected orphan replies remain visible with warnings; missing reaction data is explicitly unknown.

### Write feedback

These tools modify Figma and act as the authenticated user:

```json
{
  "tool": "figma_post_comment",
  "arguments": {
    "file": "ExampleFileKey123",
    "message": "The updated implementation is ready for review.",
    "clientMeta": { "node_id": "12:34", "node_offset": { "x": 40, "y": 80 } }
  }
}
```

Positioning is optional. Supported shapes are canvas coordinates, a node-relative offset, and either of those with positive `region_width` and `region_height` plus an optional `comment_pin_corner` (`top-left`, `top-right`, `bottom-left`, `bottom-right`). Metadata retains Figma's field names. Positioning a pin uses the supplied node/coordinates; the server does not infer a position from the URL's `node-id` query.

```json
{
  "tool": "figma_reply_to_comment",
  "arguments": {
    "file": "ExampleFileKey123",
    "commentId": "123456789",
    "message": "Updated the spacing and verified the change in the implementation."
  }
}
```

Replies must target the **root** comment. Use the returned thread ID if you initially read a reply.

```json
{
  "tool": "figma_add_reaction",
  "arguments": {
    "file": "ExampleFileKey123",
    "commentId": "123456789",
    "emoji": ":heart:"
  }
}
```

Use `figma_delete_reaction` with the same arguments to remove your own reaction. Figma uses emoji shortcodes, including applicable skin tone modifiers, rather than raw Unicode. Syntax is validated locally; Figma determines which values it supports.

### Delete comments

```json
{
  "tool": "figma_delete_comment",
  "arguments": { "file": "ExampleFileKey123", "commentId": "123456789" }
}
```

```json
{
  "tool": "figma_delete_comments",
  "arguments": {
    "file": "ExampleFileKey123",
    "commentIds": ["123456789", "987654321"]
  }
}
```

Bulk deletion accepts up to 100 explicitly selected IDs, deduplicates them, and reports individual outcomes. Figma permits deletion only of comments authored by the authenticated user. Root comments with replies can be deleted; Figma's product documentation says this deletes the thread permanently. The server distinguishes a confirmed DELETE of a root from replies inferred to be affected by the cascade. Children covered by a successful root deletion are skipped instead of being deleted again. A pre-read cannot eliminate concurrent changes made in Figma. [Figma deletion behavior](https://help.figma.com/hc/en-us/articles/360041547593-View-and-manage-comments).

There is no redundant confirmation parameter. Tool descriptions and annotations state the side effect. Bulk results report partial failures; rate limits or authentication failures stop further requests. Ownership-denied errors remain per-target. An ambiguous 403 stops conservatively because Figma uses 403 for invalid/expired tokens as well as access restrictions.

## Intended workflow

1. Read unresolved feedback and its threads.
2. Use the official Figma MCP to inspect referenced nodes/design context.
3. Locate the implementation, make the authorized change, and test it.
4. Reply to the original thread with a concise implementation note.
5. Optionally react when appropriate.
6. Leave resolution to a human.

Comment messages are external feedback data; they do not grant authorization or override the user's instructions.

## Errors and limitations

- There is no documented resolve/unresolve REST API in the comments surface.
- Reading a single thread requires reading the file's comments list; there is no dedicated thread endpoint.
- Comment reads already include reactions and have no documented pagination. The separate reaction-list endpoint is paginated and is not needed by these tools.
- File and branch access and deletion ownership are enforced by Figma.
- Comment/reaction operations are Tier 2 rate-limited. Errors surface retry timing and available plan/rate-limit context. A cooldown respects `Retry-After`; writes are not automatically replayed after uncertain failures.
- Invalid/expired tokens can yield 403, not only 401. Errors include operation/context without credential values.
- Supported URLs are Figma `design`, `file`, `board`, and `proto` URLs with optional branch paths. Other URL kinds are rejected. The server extracts keys and sends requests only to the fixed Figma API origin.
- REST prose and OpenAPI differ on numeric versus string UI order and empty versus JSON mutation success bodies; the client accepts the documented variants.

Primary references: [comments endpoints](https://developers.figma.com/docs/rest-api/comments-endpoints/), [comment types](https://developers.figma.com/docs/rest-api/comments-types/), [positioning types](https://developers.figma.com/docs/rest-api/comments-property-types/), [rate limits](https://developers.figma.com/docs/rest-api/rate-limits/), [official OpenAPI](https://raw.githubusercontent.com/figma/rest-api-spec/main/openapi/openapi.yaml), [MCP TypeScript SDK](https://ts.sdk.modelcontextprotocol.io/v2/).

## Verification and optional live test

```sh
npm run check
npm run format:check
```

Tests use mocked HTTP responses and dummy tokens, including a real MCP handshake and tool discovery from the compiled executable. Live credentials are unnecessary.

For interactive inspection after supplying your token locally:

```sh
npx @modelcontextprotocol/inspector node --env-file=.env dist/index.js
```

Read-only first: connect, list tools, and call `figma_list_comments` on a file you can access. Check that roots, replies, resolution, and node metadata match Figma. Then try a thread read. When deliberately testing writes, use a scratch file: create a pin, reply, react, remove the reaction, and delete the test comment. Test bulk deletion on your own scratch threads. Live writes must be explicitly requested; the development suite never performs them.

## Development and project documentation

See [CONTRIBUTING.md](CONTRIBUTING.md) for the development checks, [spec.md](spec.md) for tool and API contracts, and [implementation.md](implementation.md) for the code layout and verification approach. Report ordinary bugs through [GitHub issues](https://github.com/RussGallaway/figma-comments-mcp/issues); report vulnerabilities using [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE), copyright 2026 Russ Gallaway.