Content
# Custom Figma MCP
Use Codex or Claude Code to inspect and edit the Figma file that is open in Figma Desktop.
This is a local tool. It does not use the official Figma MCP, Figma OAuth, Figma API keys, file keys, or Figma web URLs for normal editing.
## Install First
### 1. Install Requirements
- Figma Desktop
- Node.js 22.5 or newer
- pnpm 10.25 or newer
If pnpm is missing, `./run.sh` will try to enable it with Corepack.
### 2. Start This Project
Open Terminal:
```bash
cd /path/to/figma-mcp
./run.sh
```
Keep this Terminal window open while you use Figma MCP.
### 3. Add The Figma Plugin Once
1. Open Figma Desktop.
2. Go to `Plugins -> Development -> Import plugin from manifest...`.
3. Select `figma-plugin/manifest.json` from this project.
4. Run `Plugins -> Development -> Custom Figma MCP Bridge`.
The plugin should show `Connected`.
### 4. Connect Your AI Tool
For Codex:
```bash
codex mcp add custom-figma-mcp -- /bin/zsh -lc 'cd /path/to/figma-mcp && node mcp-server/dist/index.js'
```
For Claude Code:
```bash
claude mcp add --transport stdio custom-figma-mcp -- /bin/zsh -lc 'cd /path/to/figma-mcp && node mcp-server/dist/index.js'
```
Use the real full path to this folder.
After adding it, restart Codex or Claude Code.
## Daily Use
1. Open the Figma file in Figma Desktop.
2. In Terminal, run:
```bash
cd /path/to/figma-mcp
./run.sh
```
3. In Figma Desktop, run `Plugins -> Development -> Custom Figma MCP Bridge`.
4. Start Codex or Claude Code.
5. Ask it to inspect or edit the open Figma file.
## Check That It Works
Run:
```bash
curl http://localhost:3333/health
```
Good result:
```json
{
"ok": true,
"pluginConnected": true
}
```
If `pluginConnected` is `false`, open Figma Desktop, open your file, and run `Plugins -> Development -> Custom Figma MCP Bridge`.
## What This Does
This project creates a local bridge:
```text
Codex / Claude Code
-> local MCP server
-> local WebSocket
-> Figma Desktop plugin
-> your open Figma file
```
The AI tool can read and edit the file that is currently open in Figma Desktop.
It can create and update frames, text, rectangles, components, auto-layout frames, styles, variables, and other supported Figma Plugin API objects.
## Common Problems
### The Plugin Says Reconnecting
1. Make sure `./run.sh` is still running.
2. Click `Reconnect` in the plugin.
3. If it still fails, close and run the plugin again from `Plugins -> Development`.
### The Health Check Says pluginConnected false
The local server is running, but Figma Desktop is not connected.
Open Figma Desktop, open the target file, and run `Custom Figma MCP Bridge`.
### Codex Or Claude Does Not Show The Tools
Restart Codex or Claude Code after adding the MCP server.
In Codex or Claude Code, run `/mcp` and look for `custom-figma-mcp`.
## More Help
- Codex setup: [docs/codex-setup.md](docs/codex-setup.md)
- Claude Code setup: [docs/claude-code-setup.md](docs/claude-code-setup.md)
- Figma plugin setup: [docs/figma-setup.md](docs/figma-setup.md)
- Architecture details: [docs/architecture.md](docs/architecture.md)
## Developer Commands
```bash
pnpm install
pnpm build
pnpm typecheck
pnpm doctor
pnpm test:integration
./run.sh --check
```
