Videntia Figma MCP

A Model Context Protocol (MCP) server that lets Claude Desktop, Claude Code, Cursor, and other AI tools interact directly with Figma.

AI Tool  ↔  MCP Server  ↔  WebSocket Server  ↔  Figma Plugin

Setup

Prerequisites

• Figma Desktop
• An AI client: Claude Desktop, Claude Code, or Cursor

Step 1 — Install the Figma Plugin

1. Download the latest videntia-figma-plugin-vX.Y.Z.zip from the Releases page
2. Unzip it anywhere on your computer
3. Open Figma Desktop
4. Go to Menu → Plugins → Development → Import plugin from manifest...
5. Select manifest.json from the unzipped folder

Step 2 — Configure MCP

Claude Code

claude mcp add videntia-figma-mcp -- npx -y @videntia/figma-mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "videntia-figma-mcp": {
      "command": "npx",
      "args": ["-y", "@videntia/figma-mcp"]
    }
  }
}

Cursor

Go to Settings → Tools & Integrations → New MCP Server and add:

{
  "mcpServers": {
    "videntia-figma-mcp": {
      "command": "npx",
      "args": ["-y", "@videntia/figma-mcp"]
    }
  }
}

Replit

Replit Agent connects to MCP servers via a remote URL (SSE), not a local command.

1. Go to Replit → Tools → Integrations → MCP Servers
2. Click Add MCP server
3. Enter name videntia-figma-mcp and URL: http://figma-mcp.videntia.dev/sse
4. Click Test & Save

Step 3 — Start the Socket Server

The socket server relays messages between your AI tool and Figma.

Option A — Hosted (default, no setup needed) A server is already running at ws://figma-mcp.videntia.dev. The plugin connects to it automatically.

Option B — Docker (self-hosted)

docker compose up -d

Option C — Bun (self-hosted)

bun run socket

When self-hosting, point the plugin to localhost instead:

# Claude Code
claude mcp add videntia-figma-mcp -- npx -y @videntia/figma-mcp --server=localhost

Step 4 — Connect to Figma

1. In Figma, run: Plugins → Development → Figma MCP
2. The plugin shows a Channel ID
3. Ask Claude: "Connect to Figma channel abc123"

Local Development

Requirements

• Bun runtime

Install and build

git clone https://github.com/rintoj/videntia-figma-mcp.git
cd videntia-figma-mcp
bun install
bun run build

bun run build does two things:

1. Regenerates src/videntia_figma_plugin/code.js from TypeScript source (what Figma loads)
2. Builds the MCP server into dist/ (what Claude connects to)

Development workflow

bun run dev          # Watch mode — rebuilds on file changes
bun run socket       # Start local WebSocket server (port 3055)
bun test --watch     # Run tests in watch mode

Point Claude Code at your local build

claude mcp add videntia-figma-mcp -s user -- node /absolute/path/to/videntia-figma-mcp/dist/videntia_figma_mcp/server.js

For Claude Desktop / Cursor, update the config to use node instead of npx:

{
  "mcpServers": {
    "videntia-figma-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/videntia-figma-mcp/dist/videntia_figma_mcp/server.js"]
    }
  }
}

After making plugin changes

Reload the plugin in Figma (close and reopen from the Plugins menu) to pick up the new code.js.

Tests

bun test                  # All tests
bun run test:coverage     # Coverage report
bun run test:integration  # Integration tests

Type checking and linting

bun run lint     # Type-check + format check
bun run format   # Auto-fix formatting

Capabilities

| Category | What you can do | | ------------- | ----------------------------------------------------------- | | Document | Read selections, inspect nodes, export assets, manage pages | | Creation | Frames, shapes, text, SVGs, components | | Modification | Colors, fills, strokes, effects, auto-layout, corner radius | | Text | Font, size, weight, spacing, line height, text styles | | Components | Create, instance, variants, properties, overrides | | Variables | Collections, tokens, modes (Light/Dark), color scales | | Design system | Spacing, typography, radius, full system initialization | | Prototyping | Reactions, connections, connector styles | | Accessibility | WCAG contrast validation, color audit |

Full command reference: see docs/

Project Files

manifest.json files

This project contains two manifest.json files with different purposes:

| File | Purpose | |------|---------| | manifest.json (root) | DXT manifest — packages the MCP server as a Claude Desktop extension (dxt_version: "0.1"). Used by bun run build:dxt. | | src/videntia_figma_plugin/manifest.json | Figma plugin manifest — tells Figma how to load the plugin (code.js + ui.html). Import this when installing the plugin in Figma. |

Troubleshooting

| Problem | Fix | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Can't connect to WebSocket | Start the socket server (bun run socket or docker compose up -d) | | Plugin not found | Re-import src/videntia_figma_plugin/manifest.json via Figma → Plugins → Development | | MCP not available in Claude Desktop | Restart Claude after editing the config file | | Font not found | Use load_font_async to verify font availability | | set_image_fill fails | Only images.unsplash.com and picsum.photos are allowed by default; add your domain to src/videntia_figma_plugin/manifest.json → networkAccess.allowedDomains | | Timeout on complex operations | Retry; large documents take longer |

License

MIT — see LICENSE