# Local Figma MCP Server

This project is a local bridge between an MCP client and Figma.

## Mental Model

There are three local pieces:

1. Your MCP client starts `node src/server.js`.
2. `src/server.js` speaks MCP over stdin/stdout.
3. The Figma plugin connects back to the server over `ws://localhost:3055`.

There is also one optional cloud piece:

4. Figma REST API calls go from `src/server.js` to `https://api.figma.com` using `FIGMA_ACCESS_TOKEN`.

The MCP server cannot directly inspect a live Figma canvas. For live canvas actions, it sends commands to the plugin, and the plugin uses the Figma Plugin API. For file metadata, comments, projects, versions, components, styles, dev resources, and webhooks, the server uses the Figma REST API.

## Why Node

Node is used because the two local edges are JavaScript-native:

- The MCP TypeScript/JavaScript SDK supports local stdio servers cleanly.
- Figma plugins are written in JavaScript.

FastAPI can work for an HTTP service, but this project is primarily a local MCP stdio server plus a WebSocket bridge to a Figma plugin. Using FastAPI would add a Python HTTP layer without removing the need for JavaScript in the plugin.

## Run The Server

```bash
npm start
```

If you want to use Figma REST API tools, set your token before starting the server:

```powershell
$env:FIGMA_ACCESS_TOKEN="your-token-here"
npm start
```

By default the server sends the token as `X-Figma-Token`, which is the usual mode for Figma personal access tokens. For OAuth bearer tokens, also set:

```powershell
$env:FIGMA_AUTH_MODE="bearer"
```

For an MCP client config, use this command:

```json
{
  "mcpServers": {
    "figma-local": {
      "command": "node",
      "args": ["C:\\Users\\Nived\\Local-Figma-MCP-server\\src\\server.js"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}
```

Do not commit a real token into this repo. Use your MCP client's private config or your shell environment.

## Load The Figma Plugin

1. Open Figma Desktop.
2. Go to `Plugins > Development > Import plugin from manifest...`.
3. Select `plugin/manifest.json`.
4. Run `Local Figma MCP Bridge`.
5. Click `Connect`.

## Current Tools

Dev-focused MVP tools:

- `get_file`: loads summarized Figma file metadata and structure.
- `find_frame`: finds a screen/frame by exact name and returns its node ID.
- `get_node`: reads details for one node.
- `export_image`: renders a frame or node as an image URL.
- `get_styles`: reads published styles for the file.
- `get_components`: reads reusable components and component sets for the file.
- `analyze_screen`: finds a frame and returns an AI-friendly dev summary with components, nested frames, text layers, colors, and counts.
Plugin-backed tools:

- `figma_status`: checks whether the plugin is connected.
- `figma_get_selection`: returns selected node summaries.
- `figma_create_rectangle`: creates a rectangle.
- `figma_create_text`: creates a text layer.

REST API-backed tools:

- `figma_api_status`: checks token configuration without exposing the token.
- `figma_me`: reads the current Figma user.
- `figma_get_file`: reads file JSON.
- `figma_get_file_metadata`: reads file metadata.
- `figma_get_file_nodes`: reads specific nodes.
- `figma_render_images`: renders image URLs for nodes.
- `figma_get_comments`: reads file comments.
- `figma_add_comment`: creates a file comment.
- `figma_delete_comment`: deletes one of your comments.
- `figma_get_file_versions`: reads file version history.
- `figma_get_team_projects`: lists team projects.
- `figma_get_project_files`: lists project files.
- `figma_get_file_components`: reads published file components.
- `figma_get_file_component_sets`: reads published file component sets.
- `figma_get_file_styles`: reads published file styles.
- `figma_get_dev_resources`: reads Dev Mode resources.
- `figma_list_webhooks`: lists accessible webhooks.
- `figma_get_team_webhooks`: lists team webhooks.

## How To Add A Plugin Tool

1. Register an MCP tool in `src/server.js`.
2. Make that tool call `bridge.sendCommand("your-command", params)`.
3. Add a matching branch in `plugin/code.js` inside `runCommand`.
4. Use the Figma Plugin API in that branch.

That pattern is the whole plugin bridge: MCP tool -> WebSocket command -> Figma Plugin API -> WebSocket result -> MCP response.

## How To Add A REST Tool

1. Register an MCP tool in `src/server.js`.
2. Validate inputs with Zod.
3. Call a method in `src/figma-api.js`.
4. `src/figma-api.js` sends an authenticated request to `https://api.figma.com`.
5. The JSON response is returned to the MCP client.