Self-Hosting Guide

Deploy your own instance of Figma Console MCP on Cloudflare Workers.

Why Self-Host?

Use the public server (https://figma-console-mcp.southleft.com) for most use cases. Self-host when:

You need guaranteed uptime/SLA
You want custom rate limits
You need enterprise security/compliance
You want to modify the code
You’re processing sensitive design data

Quick Deploy

Or via CLI:

git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
npm install
npm run deploy

Prerequisites

Cloudflare Account (free or paid)
- Sign up at https://dash.cloudflare.com/sign-up
Wrangler CLI (installed automatically via npm install)
- Cloudflare’s deployment tool
Browser Rendering API Access (required for cloud-mode console/screenshot/navigate tools)
- Free tier: 10 minutes/day, 3 concurrent browsers
- Paid tier: 10 hours/month, then $0.09/browser hour
- Automatically available on Workers
Figma OAuth App (for per-user authentication)
- Create one at https://www.figma.com/developers/apps
- Set FIGMA_OAUTH_CLIENT_ID and FIGMA_OAUTH_CLIENT_SECRET as Wrangler secrets

Step-by-Step Deployment

1. Clone and Install

git clone https://github.com/southleft/figma-console-mcp.git
cd figma-console-mcp
npm install

2. Authenticate Wrangler

npx wrangler login

This opens a browser to authenticate with Cloudflare.

3. Configure Your Deployment

Edit wrangler.jsonc (optional):

{
  "name": "figma-console-mcp",  // Change to your preferred name
  "main": "dist/index.js",
  "compatibility_date": "2024-01-01",
  "browser": {
    "binding": "BROWSER"
  },
  "limits": {
    "cpu_ms": 30000  // Adjust if needed
  }
}

4. Set Environment Variables

Required: Figma Access Token

npx wrangler secret put FIGMA_ACCESS_TOKEN
# Paste your token when prompted

Get your token at: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens

Optional: Custom Configuration

# Log level (default: info)
npx wrangler secret put LOG_LEVEL
# Enter: trace, debug, info, warn, error, or fatal

# Browser timeout (default: 120000ms)
npx wrangler secret put BROWSER_TIMEOUT
# Enter milliseconds

5. Build and Deploy

# Build for production
npm run build:cloudflare

# Deploy to Cloudflare Workers
npm run deploy

Expected output:

( Built successfully!
  Uploading...
( Deployment complete!

https://figma-console-mcp.<your-subdomain>.workers.dev

6. Test Your Deployment

# Health check
curl https://figma-console-mcp.<your-subdomain>.workers.dev/health

# Should return:
{
  "status": "healthy",
  "service": "Figma Console MCP",
  "version": "1.25.0",
  "endpoints": {
    "mcp": ["/sse", "/mcp"],
    "oauth_mcp_spec": ["/.well-known/oauth-authorization-server", "/authorize", "/token", "/oauth/register"],
    "oauth_legacy": ["/oauth/authorize", "/oauth/callback"],
    "utility": ["/health"]
  },
  "oauth_configured": true
}

7. Configure Your MCP Client

Update your AI client config to use your instance: Claude Desktop:

{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["mcp-remote", "https://figma-console-mcp.<your-subdomain>.workers.dev/sse"]
    }
  }
}

Important: Replace <your-subdomain> with your actual Cloudflare Workers subdomain.

Custom Domain (Optional)

1. Add Custom Domain in Cloudflare Dashboard

Go to Workers & Pages � figma-console-mcp
Click “Custom Domains”
Click “Add Custom Domain”
Enter your domain (e.g., mcp.example.com)
Cloudflare handles DNS automatically

2. Update MCP Client Config

{
  "mcpServers": {
    "figma-console": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.example.com/sse"]
    }
  }
}

Environment Configuration

All Available Secrets

Set these via npx wrangler secret put SECRET_NAME:

Secret	Required	Default	Description
`FIGMA_ACCESS_TOKEN`	Yes	-	Your Figma API token
`LOG_LEVEL`	No	`info`	Logging verbosity (trace/debug/info/warn/error/fatal)
`BROWSER_TIMEOUT`	No	`120000`	Browser operation timeout (ms)
`MAX_CONSOLE_LOGS`	No	`1000`	Max console logs to buffer

Setting Secrets

# Interactive (recommended)
npx wrangler secret put FIGMA_ACCESS_TOKEN

# Via file (less secure)
echo "figd_your_token" | npx wrangler secret put FIGMA_ACCESS_TOKEN

Viewing Secrets

# List all secrets (values hidden)
npx wrangler secret list

Deleting Secrets

npx wrangler secret delete SECRET_NAME

Monitoring & Logs

Real-Time Logs

# Tail production logs
npx wrangler tail

# Filter for errors
npx wrangler tail --format pretty | grep ERROR

# Filter by level
npx wrangler tail --status error

Analytics

View analytics in Cloudflare Dashboard:

Go to Workers & Pages � figma-console-mcp
Click “Analytics” tab
See:
- Request count
- Error rate
- CPU time used
- Duration percentiles

Costs

Browser Rendering API

The cloud-mode console/screenshot/navigate tools launch a headless browser via Cloudflare’s Browser Rendering API.

Free Tier: 10 minutes/day, 3 concurrent browsers
Paid Tier: 10 hours/month included, then $0.09/browser hour

Workers + Durable Objects

The deployment also uses Workers, two Durable Object classes (the MCP session and the plugin relay), and two KV namespaces for OAuth state.

Workers Free Tier: 100,000 requests/day — fine for personal use.
Workers Paid Tier ($5/month): 10 million requests/month, plus Durable Objects + KV included.

Estimated monthly cost for typical usage:

Solo developer: $0 (free tier)
Small team (5 people): $5–15/month
Medium team (20 people): $20–50/month

Updating Your Deployment

Update Code

cd figma-console-mcp
git pull origin main
npm install
npm run build:cloudflare
npm run deploy

Rollback to Previous Version

npx wrangler rollback

View Deployment History

npx wrangler deployments list

Security Best Practices

1. Protect Your Secrets

Use wrangler secret put (encrypted at rest)
L Don’t commit secrets to git
L Don’t put secrets in wrangler.jsonc

2. Token Permissions

Use a dedicated Figma access token for the MCP
Scope token to minimum required permissions
Rotate tokens periodically

3. Rate Limiting (Advanced)

For rate limiting, use Cloudflare’s built-in Rate Limiting rules:

Go to Cloudflare Dashboard → Security → WAF → Rate limiting rules
Create a rule to limit requests per IP (e.g., 100 requests/minute)
Apply to your worker’s route

Alternatively, use Cloudflare’s Rate Limiting binding for programmatic control - see Cloudflare Rate Limiting docs.

4. Access Control (Advanced)

Add authentication:

// Require API key
const authKey = request.headers.get('X-API-Key');
if (authKey !== env.API_KEY) {
  return new Response('Unauthorized', { status: 401 });
}

Then set the API key:

npx wrangler secret put API_KEY

Troubleshooting

Deployment Fails

Error: “Authentication required”

npx wrangler login

Error: “Browser Rendering not enabled”

Go to Cloudflare Dashboard
Workers & Pages → Settings
Enable Browser Rendering
Try deploying again

Error: OAuth secrets missing

Confirm wrangler secret list shows both FIGMA_OAUTH_CLIENT_ID and FIGMA_OAUTH_CLIENT_SECRET
If missing, set them via wrangler secret put FIGMA_OAUTH_CLIENT_ID and re-deploy

Browser Launch Fails

Check logs:

npx wrangler tail --format pretty

Common issues:

Browser Rendering API quota exceeded → Upgrade plan
KV namespace IDs mismatch — verify wrangler.jsonc against your account’s KV bindings
Cold start delay — normal, wait and retry
Plugin relay disconnected — Cloud Mode users need to re-pair the Desktop Bridge plugin

High Costs

Check usage:

npx wrangler metrics --worker figma-console-mcp

Reduce costs:

Implement request caching
Add rate limiting
Reduce browser timeout
Close browser sessions faster

Advanced Configuration

Custom Worker Name

// wrangler.jsonc
{
  "name": "my-custom-mcp",  // Change this
  "main": "dist/index.js",
  ...
}

Multiple Environments

Production:

npx wrangler deploy --env production

Staging:

npx wrangler deploy --env staging

Configure in wrangler.jsonc:

{
  "name": "figma-console-mcp",
  "env": {
    "production": {
      "name": "figma-console-mcp-prod",
      "vars": {
        "ENVIRONMENT": "production"
      }
    },
    "staging": {
      "name": "figma-console-mcp-staging",
      "vars": {
        "ENVIRONMENT": "staging"
      }
    }
  }
}

Durable Objects (Persistent Sessions)

For multi-user sessions, enable Durable Objects:

// wrangler.jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "SESSIONS",
        "class_name": "BrowserSession",
        "script_name": "figma-console-mcp"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_classes": ["BrowserSession"]
    }
  ]
}

CI/CD Integration

GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy to Cloudflare Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - run: npm ci
      - run: npm run build:cloudflare

      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Set secrets in GitHub:

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID

Support

For self-hosting issues:

For Cloudflare-specific issues:

​Self-Hosting Guide

​Why Self-Host?

​Quick Deploy

​Prerequisites

​Step-by-Step Deployment

​1. Clone and Install

​2. Authenticate Wrangler

​3. Configure Your Deployment

​4. Set Environment Variables

​Required: Figma Access Token

​Optional: Custom Configuration

​5. Build and Deploy

​6. Test Your Deployment

​7. Configure Your MCP Client

​Custom Domain (Optional)

​1. Add Custom Domain in Cloudflare Dashboard

​2. Update MCP Client Config

​Environment Configuration

​All Available Secrets

​Setting Secrets

​Viewing Secrets

​Deleting Secrets

​Monitoring & Logs

​Real-Time Logs

​Analytics

​Costs

​Browser Rendering API

​Workers + Durable Objects

​Updating Your Deployment

​Update Code

​Rollback to Previous Version

​View Deployment History

​Security Best Practices

​1. Protect Your Secrets

​2. Token Permissions

​3. Rate Limiting (Advanced)

​4. Access Control (Advanced)

​Troubleshooting

​Deployment Fails

​Browser Launch Fails

​High Costs

​Advanced Configuration

​Custom Worker Name

​Multiple Environments

​Durable Objects (Persistent Sessions)

​CI/CD Integration

​GitHub Actions

​Support