Imported from reason-machines/design-skills (skills/opencode-mcp-figma-auth/SKILL.md). Install upstream with npx skills add reason-machines/design-skills --skill opencode-mcp-figma-auth. Copyright stays with the author.

OpenCode MCP Figma Authentication

Skill by ara.so — Design Skills collection.

This skill enables authentication with Figma's MCP (Model Context Protocol) server for OpenCode and other AI agents. Figma MCP rejects non-whitelisted agents by default; this tool generates the required authentication file to bypass that restriction.

What It Does

OpenCode MCP Figma is a minimal authentication tool that:

Connects to Figma's MCP server at https://mcp.figma.com/mcp
Handles the OAuth-style authentication flow
Generates an mcp-auth.json file with valid credentials
Enables OpenCode and other AI agents to access Figma design data via MCP

This is specifically needed because Figma's MCP server has agent whitelisting that blocks OpenCode by default.

Installation

# Clone or navigate to the project directory
npm install
npm run build

Key Commands

Authenticate with Figma MCP

npm start https://mcp.figma.com/mcp

This command:

Initiates authentication with Figma's MCP server
Creates an mcp-auth.json file in the current directory
The file contains credentials needed for subsequent MCP connections

Install Authentication File

After authentication, move the generated file to OpenCode's MCP auth location:

# Linux/macOS
mv mcp-auth.json ~/.local/share/opencode/mcp-auth.json

# Or merge with existing file if you have other MCP authentications
cat mcp-auth.json >> ~/.local/share/opencode/mcp-auth.json

# Windows
move mcp-auth.json %LOCALAPPDATA%\opencode\mcp-auth.json

Configuration

Project Structure

opencode-mcp-figma/
├── src/
│   └── index.ts          # Main authentication logic
├── package.json
├── tsconfig.json
└── mcp-auth.json         # Generated after authentication

Generated Auth File Format

The mcp-auth.json file follows this structure:

{
  "https://mcp.figma.com/mcp": {
    "token": "generated-token-here",
    "expires": 1234567890000
  }
}

OpenCode MCP Configuration

After authentication, configure OpenCode to use Figma MCP by adding to your MCP settings:

{
  "mcpServers": {
    "figma": {
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

Code Examples

Basic Authentication Flow (TypeScript)

import { authenticate } from './src/index';

// Authenticate with Figma MCP server
const mcpUrl = 'https://mcp.figma.com/mcp';

authenticate(mcpUrl)
  .then(() => {
    console.log('Authentication successful');
    console.log('mcp-auth.json created in current directory');
  })
  .catch((error) => {
    console.error('Authentication failed:', error);
  });

Programmatic Auth File Management

import * as fs from 'fs';
import * as path from 'path';
import * as os from 'os';

// Read generated auth file
const authFile = fs.readFileSync('mcp-auth.json', 'utf-8');
const authData = JSON.parse(authFile);

// Get OpenCode's MCP auth path
const openCodeAuthPath = path.join(
  os.homedir(),
  '.local',
  'share',
  'opencode',
  'mcp-auth.json'
);

// Merge with existing auth if present
let existingAuth = {};
if (fs.existsSync(openCodeAuthPath)) {
  existingAuth = JSON.parse(fs.readFileSync(openCodeAuthPath, 'utf-8'));
}

const mergedAuth = { ...existingAuth, ...authData };

// Write merged auth
fs.mkdirSync(path.dirname(openCodeAuthPath), { recursive: true });
fs.writeFileSync(openCodeAuthPath, JSON.stringify(mergedAuth, null, 2));

console.log(`Auth file installed to ${openCodeAuthPath}`);

Verify Authentication

import * as fs from 'fs';

function verifyAuth(mcpUrl: string): boolean {
  try {
    const authFile = fs.readFileSync('mcp-auth.json', 'utf-8');
    const authData = JSON.parse(authFile);
    
    if (!authData[mcpUrl]) {
      console.error(`No authentication found for ${mcpUrl}`);
      return false;
    }
    
    const { token, expires } = authData[mcpUrl];
    
    if (!token) {
      console.error('Token is missing');
      return false;
    }
    
    if (expires && Date.now() > expires) {
      console.error('Token has expired');
      return false;
    }
    
    console.log('Authentication is valid');
    return true;
  } catch (error) {
    console.error('Failed to verify authentication:', error);
    return false;
  }
}

verifyAuth('https://mcp.figma.com/mcp');

Common Patterns

One-Time Setup Script

#!/usr/bin/env node
import { authenticate } from './src/index';
import { execSync } from 'child_process';
import * as path from 'path';
import * as os from 'os';

async function setup() {
  const mcpUrl = 'https://mcp.figma.com/mcp';
  
  console.log('Authenticating with Figma MCP...');
  await authenticate(mcpUrl);
  
  const destPath = path.join(
    os.homedir(),
    '.local',
    'share',
    'opencode',
    'mcp-auth.json'
  );
  
  console.log('Installing auth file...');
  execSync(`mkdir -p ${path.dirname(destPath)}`);
  execSync(`mv mcp-auth.json ${destPath}`);
  
  console.log('✓ Figma MCP authentication complete');
  console.log('You can now use Figma with OpenCode');
}

setup().catch(console.error);

CI/CD Authentication

// For automated environments where manual auth isn't possible
import * as fs from 'fs';

function setupAuthFromEnv() {
  const figmaToken = process.env.FIGMA_MCP_TOKEN;
  const figmaExpires = process.env.FIGMA_MCP_EXPIRES;
  
  if (!figmaToken) {
    throw new Error('FIGMA_MCP_TOKEN environment variable required');
  }
  
  const authData = {
    'https://mcp.figma.com/mcp': {
      token: figmaToken,
      expires: figmaExpires ? parseInt(figmaExpires) : undefined
    }
  };
  
  fs.writeFileSync('mcp-auth.json', JSON.stringify(authData, null, 2));
  console.log('Auth file created from environment variables');
}

Troubleshooting

Authentication Fails

Problem: Authentication command returns an error

Solutions:

Ensure you have network connectivity to https://mcp.figma.com/mcp
Check that you're using the correct MCP URL
Verify npm dependencies are installed: npm install
Rebuild the project: npm run build

Auth File Not Found by OpenCode

Problem: OpenCode doesn't recognize the authentication

Solutions:

# Verify file location
ls -la ~/.local/share/opencode/mcp-auth.json

# Check file permissions
chmod 600 ~/.local/share/opencode/mcp-auth.json

# Verify file contents
cat ~/.local/share/opencode/mcp-auth.json

Token Expired

Problem: Authentication worked initially but now fails

Solution: Re-run authentication to generate a new token:

npm start https://mcp.figma.com/mcp
mv mcp-auth.json ~/.local/share/opencode/mcp-auth.json

Multiple MCP Servers

Problem: Need to authenticate with multiple MCP servers

Solution: Merge auth files instead of overwriting:

import * as fs from 'fs';

const newAuth = JSON.parse(fs.readFileSync('mcp-auth.json', 'utf-8'));
const existingPath = '~/.local/share/opencode/mcp-auth.json';
const existing = JSON.parse(fs.readFileSync(existingPath, 'utf-8'));

const merged = { ...existing, ...newAuth };
fs.writeFileSync(existingPath, JSON.stringify(merged, null, 2));

Related Context

This tool addresses the issue described in OpenCode Issue #988 where Figma's MCP server whitelisting blocks certain AI agents. While designed for Figma, the authentication approach may work with other MCP servers that implement similar authentication mechanisms.

opencode-mcp-figma-auth

About