Figma MCP Failed to Connect: Causes and Fixes

Quick Answer

If your Figma MCP server failed to connect, work through this path first:

1. Identify which server you are using — official Figma MCP (requires Figma Desktop) or a community/third-party implementation. The fix is completely different for each.
2. Check transport — official Figma MCP uses stdio; many community servers use HTTP or SSE. A transport mismatch prevents connection before any auth check runs.
3. Check the server process — for local servers, verify the process is actually running (ps aux | grep figma or check Figma Desktop's MCP status).
4. Check authentication — verify your Personal Access Token (PAT) or OAuth token is valid, not expired, and has the correct scopes.
5. Check the URL or command — a single wrong character in the command, args, or url field silently kills the connection.

If you are using the official Figma MCP server and Figma Desktop is not open, the server does not exist. Open Figma Desktop first.

Figma MCP Failed to Connect: 60-Second Checklist

Work through this in order. Stop when you find the failure.

• Identified server type — official Figma MCP or community implementation?
• Figma Desktop is installed and running (official server only)
• MCP is enabled in Figma Desktop settings (official server only — check Figma Desktop → Preferences → Enable MCP Server)
• Transport matches — stdio for official/npx-launched, sse or http for community HTTP servers
• Command or URL is exactly correct — no typos, no extra slashes, correct port
• Access token is set — FIGMA_ACCESS_TOKEN env var or equivalent is populated and not expired
• Token has correct scopes — at minimum file:read
• File ID is accessible — the configured file exists and the token's owner can access it
• Port is not in use by another process (local/community servers)
• No proxy or VPN blocking localhost (local connections)
• MCP client version supports the server's protocol version
• Client config was saved and client was restarted after the change

Jump to the Right Fix

Identifying Your Figma MCP Implementation

This is the most important step. The official Figma MCP server and community implementations are architecturally different. Mixing their documentation causes every symptom listed in the table above.

Official Figma MCP Server

Figma's official MCP server is distributed as part of Figma Desktop and also available as an npm package (@figma/mcp). Key characteristics:

• Requires Figma Desktop installed and running (for the Desktop-integrated version)
• Uses stdio transport — it is launched as a child process by the MCP client
• Authentication is handled through your active Figma Desktop session or a PAT
• Documented at figma.com/developers/mcp
• The command in your client config points to npx @figma/mcp or Figma Desktop exposes it directly

Community / Third-Party Figma MCP Servers

There are several popular community implementations (e.g., figma-mcp, figma-developer-mcp, and others on GitHub). These:

• Call the Figma REST API directly using a Personal Access Token
• Typically use HTTP or SSE transport and run on a local port (often 3000 or 3333)
• Do not require Figma Desktop to be running
• Require a FIGMA_ACCESS_TOKEN environment variable or similar
• Are configured with a url field pointing to http://localhost:PORT/sse or similar

How to identify which one you have:

# Look at your MCP client config
cat ~/.cursor/mcp.json
# or
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

If the config has a command field with npx @figma/mcp or similar → official server, stdio transport.

If the config has a url field pointing to http://localhost:3000 or similar → community server, HTTP/SSE transport.

If you are unsure which package you installed, check:

npx @figma/mcp --version
# or check your package.json / global installs
npm list -g | grep figma

Checking Official Prerequisites and Current Connection Method

For the official Figma MCP server, these prerequisites must all be true before a connection is possible:

Figma Desktop Requirements

1. Figma Desktop must be installed — the web app does not include the MCP server.
2. Figma Desktop must be running and you must be logged in.
3. MCP must be enabled in Figma Desktop preferences. Navigate to: Figma Desktop → Preferences (or Settings) → Enable MCP Server. If this toggle is off, the server process never starts.
4. After enabling, restart Figma Desktop to ensure the server process initializes.

npx / npm Method

If you are using npx @figma/mcp directly (without relying on Desktop integration), you still need:

• Node.js 18 or higher
• A valid Figma Personal Access Token with file:read scope
• The token set as FIGMA_PERSONAL_ACCESS_TOKEN in the environment where the MCP client launches the process

Verify Node.js version:

node --version
# Must be >= 18.0.0

Verify the package resolves:

npx --yes @figma/mcp --help

If this command fails, the issue is npm/npx resolution — not your MCP client config.

Verifying the Exact Server URL and Transport

A mismatched transport or malformed command is the single most common cause of "Figma MCP failed to connect" errors that produce no useful error message.

Official Server (stdio)

Your Claude Desktop config should look like this:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@figma/mcp"],
      "env": {
        "FIGMA_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Your Cursor config (~/.cursor/mcp.json) follows the same structure.

Common mistakes:

Community Server (HTTP/SSE)

For community servers, the config uses url instead of command:

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3333/sse",
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

The port and path vary by implementation. Check the server's README for the exact endpoint. Common defaults:

• http://localhost:3000/sse
• http://localhost:3333/sse
• http://localhost:3000/mcp

Verify the server is running and the endpoint exists:

curl -i http://localhost:3333/sse
# Should return 200 with text/event-stream content-type
# Connection refused = server not running
# 404 = wrong path

Fixing Local Figma MCP Connection Failures

Official Server: Process Not Starting

Symptom: spawn ENOENT, command not found, or immediate connection failure.

Verify:

# Check npx is available
which npx

# Try launching the server manually
FIGMA_PERSONAL_ACCESS_TOKEN=your-token npx -y @figma/mcp
# Should start and wait for stdin — if it exits immediately, note the error

Fix: If npx is not found, the MCP client is not inheriting your shell PATH. Add the full path to npx in the config:

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

Find the full path with which npx.

Confirm recovery: The server process stays running when you launch it manually. The MCP client shows Figma tools after restart.

Community Server: Port Conflict or Server Not Running

Symptom: Connection refused on the configured port.

Verify:

# Check if anything is listening on the expected port
lsof -i :3333
# or on Windows:
netstat -ano | findstr :3333

If nothing is listed, the server is not running. Start it according to the community server's documentation.

If something else is using the port:

# Kill the conflicting process (replace PID)
kill -9 <PID>
# Or change the server port and update your MCP client config

VPN and Localhost Blocking:

Some VPNs (Cisco AnyConnect, Palo Alto GlobalProtect) intercept loopback traffic. Test:

# Disconnect VPN and retry the connection
# If it works, configure a split-tunnel exception for 127.0.0.1

Confirm recovery: curl -i http://localhost:3333/sse returns 200. Tools appear in the MCP client.

Fixing Remote Figma MCP Connection Failures

The official Figma MCP server does not support remote connections — it is a local-only server. If you need to call Figma from a remote environment (CI, cloud agent, remote dev box), you must use a community server deployed as a persistent process on a reachable host.

For remote community server connections:

Symptom: Timeout or connection refused to a non-localhost URL.

Verify:

curl -i https://your-figma-mcp-server.example.com/sse

Common causes and fixes:

Nginx SSE fix (a frequently missed configuration that causes SSE connections to silently drop):

location /sse {
  proxy_pass http://localhost:3333;
  proxy_http_version 1.1;
  proxy_set_header Connection '';
  proxy_buffering off;
  proxy_cache off;
  proxy_read_timeout 3600s;
}

Authentication and Permission Errors

HTTP 401 — Token Missing or Invalid

Symptom: Server responds with 401 Unauthorized. For stdio servers, you may see an auth error printed to stderr.

Verify your token:

curl -H "X-Figma-Token: your-token" \
  https://api.figma.com/v1/me
# Should return your user info
# 401 = token is wrong or expired

Fix:

1. Go to figma.com → Account Settings → Personal Access Tokens
2. Generate a new token with at least File content: Read scope
3. Update the token in your MCP client config or environment variable
4. Restart the MCP client

Token scope requirements for common Figma MCP tools:

If you use the newer OAuth-based token generation in Figma (available to Enterprise teams), ensure you selected the correct scopes when creating the OAuth app.

HTTP 403 — Permission Denied

Symptom: Token is valid but you get 403 Forbidden.

Common causes:

• The token belongs to a user who is not a member of the team or project that owns the file
• The file is in a draft (personal drafts) folder — some API endpoints do not work on drafts
• The file has been moved to a different team where your account lacks access
• The Figma plan does not include API access for this feature (some features are Enterprise-only)

Fix:

# Verify file accessibility with the token
curl -H "X-Figma-Token: your-token" \
  "https://api.figma.com/v1/files/YOUR_FILE_ID"
# 200 = accessible
# 403 = no permission — share the file with the token owner's account

Share the file explicitly with the account that owns the token, or use a token from an account that already has access.

Expired or Revoked Tokens

Figma Personal Access Tokens do not expire by default, but they can be:

• Manually revoked from Account Settings
• Automatically invalidated when the account password changes
• Invalidated if SSO/SAML settings change in an enterprise org

If a token that was working suddenly stops, check Account Settings → Personal Access Tokens to confirm it still exists. If not, generate a new one.

HTTP and Network Troubleshooting

HTTP 404 — Wrong Endpoint

For community servers, the MCP endpoint path varies. A 404 means the server is running but the path is wrong.

# Try common paths
curl -i http://localhost:3333/
curl -i http://localhost:3333/sse
curl -i http://localhost:3333/mcp
curl -i http://localhost:3333/v1/sse

Check the community server's documentation or source code for the correct route.

HTTP 429 — Rate Limited

Figma's API has rate limits. If a tool makes many API calls rapidly (e.g., reading a large file with many nodes), you may hit the limit.

Fix: The community server or your client should implement exponential backoff. If you control the server code:

async function fetchWithRetry(url: string, options: RequestInit, retries = 3): Promise<Response> {
  const response = await fetch(url, options);
  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '5', 10);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return fetchWithRetry(url, options, retries - 1);
  }
  return response;
}

HTTP 5xx — Figma API or Server Error

5xx errors from the Figma API are transient. Check status.figma.com for active incidents. If the server is your own community deployment, check its logs:

# Check server logs (example for PM2-managed process)
pm2 logs figma-mcp

# Or check systemd
journalctl -u figma-mcp -n 100

Proxy and Corporate Firewall Issues

If you are behind a corporate proxy:

# Test connectivity through the proxy
curl --proxy http://proxy.corp.com:8080 \
  -H "X-Figma-Token: your-token" \
  https://api.figma.com/v1/me

For Node.js-based servers, set the proxy environment variable:

export HTTPS_PROXY=http://proxy.corp.com:8080
export HTTP_PROXY=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1

For stdio-transport servers launched by an MCP client, add these to the env block in your config:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@figma/mcp"],
      "env": {
        "FIGMA_PERSONAL_ACCESS_TOKEN": "your-token",
        "HTTPS_PROXY": "http://proxy.corp.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

TLS / Certificate Issues

# Diagnose TLS handshake
openssl s_client -connect your-figma-mcp-server.example.com:443 -servername your-figma-mcp-server.example.com

# Check certificate expiry
echo | openssl s_client -connect your-figma-mcp-server.example.com:443 2>/dev/null | openssl x509 -noout -dates

If the cert is self-signed and your MCP client rejects it, configure the server with a valid certificate (Let's Encrypt is free) or set NODE_TLS_REJECT_UNAUTHORIZED=0 only in a local development environment. Never disable TLS verification in production.

Client-Specific Configuration Problems

Claude Desktop

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Common mistake — invalid JSON after manual edits:

# Validate the JSON before restarting Claude
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

Claude Desktop reads the config only on startup. If you edited the file while Claude was running, the change has no effect until you fully quit and relaunch.

Claude Desktop shows MCP server status in Settings → Developer. A red dot next to the server name means the connection failed — hover or click for the error message.

Cursor

Config file: ~/.cursor/mcp.json

Cursor supports both stdio and sse transports. Verify:

cat ~/.cursor/mcp.json | python3 -m json.tool

After editing, open Cursor Settings → MCP and click the refresh icon to force a reconnect without restarting Cursor entirely.

Cursor also surfaces MCP errors in the Output panel — open View → Output and select the MCP channel from the dropdown.

Windsurf / Codeium

Windsurf's MCP config follows the same structure as Cursor. Config location: ~/.windsurf/mcp.json. After a config change, use Windsurf → Reload MCP Servers from the command palette.

Figma MCP Works in One Client but Fails in Another

This is almost always a config format difference between clients, not a server problem.

Diagnostic steps:

1. Confirm the server works by testing it with MCP Inspector (see below).
2. Compare the configs between the working and failing client — check for missing env fields, wrong transport type, or differences in args.
3. Check that the failing client's config file is in the correct location for that client.
4. Verify the failing client was fully restarted after the config change.

For clients that use sse transport, ensure the community server is running before the client starts. Clients that use stdio start the server process themselves — the server does not need to be pre-running.

Figma MCP Connects but Tools Are Missing

A successful MCP connection that returns zero tools is a distinct failure mode. The handshake succeeded, but tools/list returned empty or the client isn't calling it.

Verify using MCP Inspector:

npx @modelcontextprotocol/inspector

Connect to your Figma MCP server and manually call tools/list. If it returns tools in Inspector but not in your client, the issue is client-side. If it returns empty in Inspector too, the issue is server-side.

Server-side causes of empty tools:

Client-side causes:

• Client MCP protocol version is incompatible with the server — check both versions
• Client filters tools by capability or namespace — check client settings
• Client caches tool list — force a refresh or restart the client

Connection Stopped Working After an Update

If a previously working Figma MCP connection suddenly fails, narrow it down:

Was Figma Desktop updated?

• Figma Desktop auto-updates. A major update can reset MCP preferences or change how the local server starts.
• Check: Open Figma Desktop → Preferences → confirm MCP Server is still enabled.
• Fix: Re-enable MCP, restart Desktop, restart your MCP client.

Was the MCP client updated?

• Claude Desktop, Cursor, and Windsurf all update frequently. Updates can change the expected config format or transport behavior.
• Check: Review the client's changelog for MCP-related changes.
• Fix: Validate your config against the updated client's current documentation.

Was the community server package updated?

• If you run npx package@latest in args, an upstream breaking change can break your setup.
• Fix: Pin to a known-good version: "args": ["-y", "some-figma-mcp@1.2.3"]

Did your Figma token change?

• Check Account Settings → Personal Access Tokens. If the token was regenerated (by you or an admin), the old value stored in your config is invalid.
• Fix: Update the token in every config file and env var that references it.

Regression test:

# Test the token is still valid
curl -H "X-Figma-Token: your-token" https://api.figma.com/v1/me

# Test the server starts cleanly (stdio)
FIGMA_PERSONAL_ACCESS_TOKEN=your-token npx -y @figma/mcp

# Test the local endpoint (HTTP/SSE)
curl -i http://localhost:3333/sse

Testing with MCP Inspector

MCP Inspector is the fastest way to isolate whether a Figma MCP connection problem is in the server, the client, or the network. It connects directly to the server and lets you call any MCP method interactively.

For a comprehensive walkthrough of Inspector's capabilities, see the MCP Inspector complete guide on MCPForge.

Launch Inspector:

npx @modelcontextprotocol/inspector

This opens a browser UI at http://localhost:5173.

For stdio servers (official Figma MCP):

In Inspector, select stdio as transport. Set the command to npx and args to -y @figma/mcp. Add FIGMA_PERSONAL_ACCESS_TOKEN to the environment variables panel. Click Connect.

For HTTP/SSE servers (community):

In Inspector, select SSE as transport. Enter http://localhost:3333/sse as the URL. Click Connect.

What to check in Inspector:

1. Initialize handshake — does it complete without error?
2. tools/list — does it return tools? How many? What are their names?
3. Call a tool — does a simple tool like get_file or equivalent return data?
4. Error messages — Inspector shows the raw JSON-RPC error, which is far more diagnostic than what MCP clients surface.

If Inspector connects successfully but your MCP client does not, the problem is definitively in your client configuration, not the server.

You can also use MCPForge's MCP server testing tool to run a quick validation against HTTP-accessible servers.

Minimal Reproduction

Before filing a bug, reduce the problem to its smallest reproducible form. This helps both you and the maintainers identify the root cause quickly.

Steps:

1. Isolate the server — test with MCP Inspector before involving any client.
2. Isolate the client — test the same config with a second client (if you have one).
3. Isolate the network — test on a direct connection without VPN or proxy.
4. Isolate the token — generate a fresh token and test with only file:read scope.
5. Isolate the package version — try npx -y @figma/mcp@latest to rule out stale cache.

Minimal reproduction config (stdio, official server):

{
  "mcpServers": {
    "figma-minimal": {
      "command": "npx",
      "args": ["-y", "@figma/mcp"],
      "env": {
        "FIGMA_PERSONAL_ACCESS_TOKEN": "fresh-token-here"
      }
    }
  }
}

If this minimal config also fails, the problem is in the server package or the environment — not your client config complexity.

Bug Report Checklist

When reporting a Figma MCP connection error to Figma support or the community server maintainer, include:

• Server type: Official (@figma/mcp) or community (name + version)
• Server version: npx @figma/mcp --version or package.json version
• MCP client: Claude Desktop, Cursor, Windsurf, etc. — include version
• Transport: stdio, SSE, or HTTP
• Operating system and version
• Node.js version: node --version
• Exact error message: full text, not paraphrased
• MCP Inspector result: did it connect? what did tools/list return?
• Network environment: direct connection, VPN, corporate proxy?
• Figma Desktop version (if using official server)
• Token validity: confirmed with curl https://api.figma.com/v1/me
• Steps to reproduce: minimal config that reproduces the issue
• What changed: did it ever work? what changed before it broke?

Do not include your actual access token in a bug report. Replace it with REDACTED before sharing any config or log output.

Prevention Best Practices

Avoid future Figma MCP connection failures with these habits:

Token hygiene:

• Store tokens in environment variables or a secrets manager, not hardcoded in config files.
• Use a dedicated Figma service account for shared team setups — personal tokens get invalidated when individuals change passwords or leave.
• Document when a token was generated and rotate it on a schedule.

Config discipline:

• Keep MCP client configs in version control (with tokens replaced by env var references).
• Validate JSON before saving: python3 -m json.tool your-config.json.
• Pin community server versions in args: @some-figma-mcp@1.2.3 instead of @latest.

Monitoring:

• For community servers running in production, add a health check endpoint and monitor it.
• For teams, document the MCP server setup in a shared runbook so token rotation and Figma Desktop updates can be coordinated.

Before updating anything:

• Read changelogs for your MCP client and Figma MCP server before updating.
• Test the connection in MCP Inspector after any update before assuming it works in the full client.

For more on keeping MCP servers stable in production environments, see running MCP in production.

For a broader look at connection failures across different MCP server types, the MCP failed to connect troubleshooting guide covers general patterns that apply when Figma-specific steps don't resolve the issue.

Architecture: How the Official Figma MCP Server Connects

┌─────────────────────────────────────────────────────────┐
│                    Your Machine                         │
│                                                         │
│  ┌──────────────────┐    stdio     ┌─────────────────┐  │
│  │   MCP Client     │◄────────────►│  @figma/mcp     │  │
│  │ (Claude Desktop, │   (stdin/   │  (Node process  │  │
│  │  Cursor, etc.)   │   stdout)   │   via npx)      │  │
│  └──────────────────┘             └────────┬────────┘  │
│                                            │            │
│                                            │ HTTPS      │
│                                            │ REST API   │
└────────────────────────────────────────────┼────────────┘
                                             │
                                    ┌────────▼────────┐
                                    │   Figma API     │
                                    │ api.figma.com   │
                                    └─────────────────┘

The MCP client spawns the @figma/mcp process as a child. All JSON-RPC communication happens over stdin/stdout on your local machine. The server then makes outbound HTTPS calls to api.figma.com on your behalf using your PAT. There is no intermediate relay — which means both local process execution and outbound HTTPS must work.

┌─────────────────────────────────────────────────────────┐
│              Community Server Architecture              │
│                                                         │
│  ┌──────────────────┐    SSE/HTTP  ┌─────────────────┐  │
│  │   MCP Client     │◄────────────►│ Community MCP   │  │
│  │                  │  localhost:  │ Server Process  │  │
│  │                  │  3333/sse    │ (Node/Python)   │  │
│  └──────────────────┘             └────────┬────────┘  │
│                                            │            │
└────────────────────────────────────────────┼────────────┘
                                             │ HTTPS + PAT
                                    ┌────────▼────────┐
                                    │   Figma REST    │
                                    │     API         │
                                    └─────────────────┘

Community servers run as persistent HTTP servers. The MCP client connects over HTTP or SSE. The community server authenticates to Figma's API using a PAT from its environment. Both processes must be running, and the HTTP layer between them must be clear.

Understanding which architecture you are in determines which layer to debug first.