# Claude Code ↔ Figma Bridge Setup Guide
## Overview
This system enables real-time communication between Claude Code and Figma, allowing you to create and manipulate Figma designs through natural language commands. The bridge consists of two main components:
- **MCP Server**: A Node.js server that implements the Model Context Protocol, exposing tools for Figma design manipulation
- **Figma Plugin**: A plugin that runs inside the Figma desktop app and communicates with the MCP server via HTTP
## Architecture
```
Claude Code
↓ (stdio)
MCP Server (Node.js, port 3001)
↓ (HTTP polling)
Figma Plugin (runs inside Figma)
↓
Figma Desktop App
```
The MCP server acts as a bridge:
- Listens for commands from Claude Code via standard input/output
- Exposes an HTTP API on port 3001 for the Figma plugin to poll
- Executes design commands in Figma through the plugin
## Prerequisites
- Node.js 18 or later installed
- npm (comes with Node.js)
- Figma desktop app installed
- Claude Code CLI installed and configured
## Installation
### 1. Install MCP Server Dependencies
Navigate to the mcp-server directory and install dependencies:
```bash
cd mcp-server
npm install
```
### 2. Install Figma Plugin Dependencies
Navigate to the figma-plugin directory and install dependencies:
```bash
cd figma-plugin
npm install
```
### 3. Build the MCP Server
Build the TypeScript source code:
```bash
cd mcp-server
npm run build
```
This creates compiled JavaScript in the `dist/` directory.
### 4. Build the Figma Plugin
Build the plugin code:
```bash
cd figma-plugin
npm run build
```
This creates `dist/code.js` and `dist/ui.html`.
## Configuration
### Step 1: Configure Claude Code MCP Connection
Edit your Claude Code configuration file to register the Figma bridge MCP server.
**On Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
**On macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**On Linux:**
```
~/.config/Claude/claude_desktop_config.json
```
Add the following configuration block (create the file if it doesn't exist):
```json
{
"mcpServers": {
"figma-bridge": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/index.js"],
"env": {
"HTTP_PORT": "3001"
}
}
}
}
```
**Important:** Replace `/absolute/path/to/mcp-server/dist/index.js` with the full path to your mcp-server dist directory.
For example on Windows:
```json
"args": ["D:/figma_mcp_test/mcp-server/dist/index.js"]
```
### Step 2: Configure API Key Authentication
The MCP server uses X-API-Key authentication to secure communication:
| Variable | Description | Default |
|----------|-------------|---------|
| `API_KEY` | API key for request authentication | `dev-secret-key` |
| `HTTP_PORT` | HTTP server port for Figma plugin communication | `3001` |
| `NODE_ENV` | Environment mode | `development` |
**For Development:** The default API key is `dev-secret-key` (defined in server.ts). This is used for local development and should be kept in the Figma plugin configuration.
**Important:** Keep the API key secure. For production, use a strong, unique key and implement proper key management.
You can set these in the Claude Code config file under the `env` section (as shown above) or in your system environment.
### Step 3: Load the Figma Plugin
1. Open the **Figma desktop app**
2. Go to **Plugins** menu → **Development** → **Import plugin from manifest...**
3. Navigate to and select: `D:\figma_mcp_test\figma-plugin\manifest.json`
4. The plugin "Claude Code Bridge" will now appear in your Plugins menu
Keep this plugin loaded while using the Claude Code bridge.
### Step 4: Configure Plugin API Key
When you run the Figma plugin for the first time, you'll be prompted to enter the API key:
- **Default Development Key:** `dev-secret-key`
Enter this key in the plugin panel. The plugin will use it for all requests to the MCP server.
## Running the System
### 1. Verify MCP Server is Connected
Once you've configured Claude Code and restarted it, the MCP server should automatically start when Claude Code runs. You'll see the tools registered:
```
[MCP] Starting Figma Bridge MCP Server...
[MCP] Tools registered: create_rect, create_text, create_frame, set_fill, move_node, delete_node
[MCP] Connected to stdio transport
```
### 2. Run the Figma Plugin
1. In Figma, open a design file (create one if needed)
2. Go to **Plugins** → **Development** → **Claude Code Bridge**
3. The plugin will open a panel showing connection status
4. Enter the API Key: `dev-secret-key` (default for development)
5. The server endpoint is: `http://localhost:3001` (default)
The plugin will now poll the MCP server for commands using the authenticated connection.
### 3. Start Using Claude Code
You're now ready to use Claude Code to create Figma designs!
## Usage Examples
### Create Shapes
Create a blue rectangle:
```
"Create a blue rectangle at position 100, 100 with width 200 and height 150"
```
Create a red circle:
```
"Create a red ellipse at 50, 50 with size 100x100"
```
Create a green frame:
```
"Create a frame named 'Header' at position 0, 0 with width 1440 and height 80"
```
### Add Text
```
"Add text saying 'Welcome' at position 100, 100 with font size 32"
```
### Modify Existing Elements
```
"Change the fill color of the rectangle to orange"
"Move the text element to position 200, 300"
"Delete the blue circle"
```
### Complex Layouts
```
"Create a card layout with a white frame at 0, 0 (400x500), add a header text, a divider line, and content area"
```
## Available Tools
These tools are available to Claude Code and the Figma plugin:
| Tool | Parameters | Description |
|------|-----------|-------------|
| `create_rect` | x, y, width, height, fill, name | Create a rectangle |
| `create_text` | x, y, text, fontSize, fill, name | Create a text element |
| `create_frame` | x, y, width, height, name | Create a frame (container) |
| `set_fill` | nodeId, color | Change the fill color of an element |
| `move_node` | nodeId, x, y | Move an element to a new position |
| `delete_node` | nodeId | Delete an element |
## Troubleshooting
### Plugin Shows "Connection Failed"
**Problem:** The plugin cannot connect to the MCP server.
**Solutions:**
1. Verify the MCP server is running - check Claude Code console for startup messages
2. Confirm the HTTP endpoint in the plugin matches your configuration (default: `http://localhost:3001`)
3. Ensure port 3001 is not blocked by a firewall
4. Check that the MCP server was built: `npm run build` in mcp-server/
### Commands Timeout or Don't Execute
**Problem:** Figma commands don't execute within 10 seconds.
**Solutions:**
1. Verify the Figma plugin is running and the panel is open
2. Check that you have an open Figma design file
3. Look at the Figma plugin panel for error messages
4. Open Figma's developer console: **Help** → **Toggle Developer Tools** and check for errors
### Port 3001 Already in Use
**Problem:** Another application is using port 3001.
**Solutions:**
1. Find the process using port 3001:
- Windows: `netstat -ano | findstr :3001`
- macOS/Linux: `lsof -i :3001`
2. Either stop the conflicting application or configure a different port
3. Change the HTTP_PORT environment variable in your Claude Code config
### Plugin Manifest Import Error
**Problem:** "Failed to import plugin" when trying to load the manifest.
**Solutions:**
1. Ensure the figma-plugin has been built: `npm run build` in figma-plugin/
2. Verify the manifest.json file exists at: `figma-plugin/manifest.json`
3. Check that the path in the import dialog is correct and uses forward slashes
4. Try restarting the Figma desktop app
### CORS or Network Errors in Figma
**Problem:** Network errors appear in the Figma plugin console.
**Solutions:**
1. The HTTP server is configured for local development with permissive CORS
2. Ensure you're running on `localhost` (not a different hostname)
3. Verify firewall settings allow localhost connections
4. Check that NODE_ENV is set to `development`
## Development
### Run MCP Server in Development Mode
For active development with auto-recompilation:
```bash
cd mcp-server
npm run dev
```
This uses `tsx watch` to automatically rebuild on file changes.
### Run Figma Plugin in Development Mode
For development, the plugin auto-reloads when you save code. Rebuild when needed:
```bash
cd figma-plugin
npm run build
```
Then reload the plugin in Figma: right-click the plugin → Reload.
### Run Tests
For the MCP server:
```bash
cd mcp-server
npm run test
npm run test:watch
```
For the figma-plugin (if tests exist):
```bash
cd figma-plugin
npm run test
```
## File Structure
```
D:\figma_mcp_test\
├── mcp-server/ # MCP server implementation
│ ├── src/
│ │ ├── index.ts # Main server entry point
│ │ ├── http/ # HTTP server for plugin communication
│ │ ├── tools/ # Tool implementations
│ │ ├── queue/ # Command queuing system
│ │ ├── types/ # TypeScript type definitions
│ │ └── __tests__/ # Tests
│ ├── dist/ # Compiled JavaScript (generated)
│ ├── package.json
│ └── tsconfig.json
├── figma-plugin/ # Figma plugin implementation
│ ├── src/
│ │ ├── code.ts # Plugin main code
│ │ ├── ui.ts # Plugin UI logic
│ │ └── handlers/ # Event handlers
│ ├── dist/ # Compiled plugin files (generated)
│ ├── manifest.json # Figma plugin manifest
│ ├── build.js # Build configuration
│ └── package.json
└── docs/
└── setup.md # This file
```
## Security Considerations
This bridge is designed for local development:
- HTTP server listens on `localhost:3001` only
- Figma plugin only connects to `localhost:3001` (see manifest.json)
- X-API-Key authentication is implemented (default key: `dev-secret-key` for development)
- The MCP server has full access to Figma documents through the plugin
For production use, you would need to:
- Implement authentication/authorization
- Use HTTPS instead of HTTP
- Restrict tool access
- Add audit logging
## Next Steps
1. Complete the setup steps above
2. Open a Figma design file
3. Use Claude Code to create designs: "Create a simple header section with a blue background"
4. Check the Figma canvas for the created elements
5. Explore more complex design generation
## Support
For issues or questions:
1. Check the Troubleshooting section above
2. Review the MCP server logs in Claude Code console
3. Check the Figma plugin console (Help → Toggle Developer Tools)
4. Verify all build steps completed successfully
