tr-figma-mcpserver

Hosted MCP (Model Context Protocol) server for downloading Figma images using access tokens.

Quick Start

1. Install the Package

npm install -g @somnathroy/tr-figma-mcpserver

Or use with npx (no installation):

npx @somnathroy/tr-figma-mcpserver

2. Get Your Figma Access Token

1. Go to Figma Settings

2. Scroll to "Personal access tokens"

3. Click "Create new token"

4. Give it a name (e.g., "MCP Server")

5. Copy the token (format: figd_...)

3. Configure Your MCP Client

Create .mcp.json in your project root or add to your MCP client config:

Using installed package:

{
  "mcpServers": {
    "tr-figma-mcpserver": {
      "command": "tr-figma-mcpserver",
      "env": {
        "MCP_STDIO": "true",
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
      }
    }
  }
}

Using npx (no installation):

{
  "mcpServers": {
    "tr-figma-mcpserver": {
      "command": "npx",
      "args": ["-y", "@somnathroy/tr-figma-mcpserver"],
      "env": {
        "MCP_STDIO": "true",
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
      }
    }
  }
}

Configuration Locations:

• VS Code / Cursor: .mcp.json in project root or .vscode/mcp.json

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

4. Verify Setup

Check that the MCP server appears in your MCP client:

• In VS Code: Check the MCP panel/output

• In Cursor: Settings → MCP Servers

• In Claude Desktop: Check logs

5. Use the Tool

Once configured and loaded, use the download_figma_images tool:

Basic usage:

{
  "figmaUrl": "https://www.figma.com/design/WJNNpEsralNcSMptsFbFH9/LT-Matters-page?node-id=29302-167474"
}

With options:

{
  "figmaUrl": "https://www.figma.com/design/WJNNpEsralNcSMptsFbFH9/LT-Matters-page?node-id=29302-167474",
  "format": "png",
  "scale": 2
}

That's it! No need to pass the token in every request since it's configured in your MCP client settings.

Related MCP server: OpenFigma MCP

Features

• ✅ Download images from Figma files using access tokens

• ✅ Supports both /file/ and /design/ URL formats

• ✅ Automatic node-id parameter conversion (hyphen to colon format)

• ✅ Multiple export formats: PNG, JPG, SVG, PDF

• ✅ Configurable scale factor for raster images (0.01 to 4)

• ✅ Base64-encoded responses for easy integration

• ✅ Hosted on Azure Web App - no installation required

• ✅ Configure token once, use everywhere

Supported URL Formats

The server supports both Figma URL formats:

1. File URLs: https://www.figma.com/file/{fileId}/{fileName}

2. Design URLs: https://www.figma.com/design/{fileId}/{fileName}?node-id=123-456

Node ID Conversion

The server automatically converts node IDs from URL format to API format:

• URL format: node-id=29302-167474 (hyphen separator)

• API format: 29302:167474 (colon separator)

Example:

• Input: https://www.figma.com/design/WJNNpEsralNcSMptsFbFH9/LT-Matters-page?node-id=29302-167474

• Parsed: File ID WJNNpEsralNcSMptsFbFH9, Node ID 29302:167474

API Reference

Tool: download_figma_images

Downloads images from Figma designs and returns them as Base64-encoded resources.

Parameters

Response

{
  "content": [
    {
      "type": "text",
      "text": "Downloaded 1 image from Figma file: LT Matters page"
    },
    {
      "type": "resource",
      "resource": {
        "uri": "data:image/png;base64,iVBORw0KGgo...",
        "mimeType": "image/png",
        "text": "Node 29302:167474 (245.67 KB)"
      }
    }
  ]
}

Error Handling

The server returns helpful error messages for common issues:

Health Check

Verify the service is running:

curl https://tr-figma-mcpserver-gsakbybcgegzdkc4.centralus-01.azurewebsites.net/health

Expected response:

{
  "status": "healthy",
  "service": "tr-figma-mcpserver",
  "version": "1.0.0",
  "timestamp": "2026-04-01T12:00:00.000Z"
}

Security

Token Handling

• Server does NOT store tokens: Tokens are passed per-request or via environment variables

• No logging: Tokens are never logged or persisted

• User responsibility: Users secure their own Figma tokens

• HTTPS required: All communication encrypted in transit (Azure provides SSL/TLS)

Best Practices

1. ✅ Never commit tokens to git repositories

2. ✅ Store tokens in environment variables or secure configuration

3. ✅ Rotate tokens regularly

4. ✅ Use separate tokens for different services

5. ✅ Revoke tokens immediately if compromised

6. ✅ Only share tokens with trusted MCP clients

Troubleshooting

"No token provided"

Problem: Neither figmaAccessToken parameter nor FIGMA_ACCESS_TOKEN environment variable is set.

Solution:

• Add token to your MCP client config's env section, OR

• Provide figmaAccessToken in each request

"Unauthorized: Invalid or expired token"

Problem: Your Figma token is incorrect or has expired.

Solution:

• Verify token format (should start with figd_)

• Check if token was revoked in Figma settings

• Generate a new token at https://www.figma.com/settings

"Invalid Figma URL format"

Problem: URL doesn't match expected Figma format.

Solution:

• Ensure URL starts with https://www.figma.com/

• URL must contain /file/ or /design/ path

• Example: https://www.figma.com/design/{fileId}/{name}?node-id=123-456

"No node IDs specified"

Problem: Neither nodeIds parameter nor node-id in URL provided.

Solution:

• Add nodeIds parameter: ["123:456", "789:012"], OR

• Include node-id in URL: ?node-id=123-456

"Failed to download image"

Problem: Network issue or Figma API error.

Solution:

• Check your internet connection

• Verify the node exists in the Figma file

• Try a smaller scale factor for large images

• Wait a moment if rate limited

Development & Local Setup

Want to run the server locally or contribute to development?

Prerequisites

• Node.js 22+ installed

• npm or yarn package manager

• Git

Local Installation

1. Clone the repository:

git clone https://github.com/your-org/tr-figma-mcpserver.git
cd tr-figma-mcpserver

2. Install dependencies:

npm install

3. Build TypeScript:

npm run build

4. Run locally:

npm run dev

Local MCP Configuration

To use your local instance instead of the hosted one:

{
  "mcpServers": {
    "tr-figma-mcpserver": {
      "command": "node",
      "args": ["C:/path/to/tr-figma-mcpserver/dist/index.js"],
      "env": {
        "MCP_STDIO": "true",
        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
      }
    }
  }
}

Testing Locally

Test the health endpoint:

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "service": "tr-figma-mcpserver",
  "version": "1.0.0",
  "timestamp": "..."
}

Project Structure

tr-figma-mcpserver/
├── src/
│   ├── index.ts              # Express server + SSE/stdio transports
│   ├── server.ts             # MCP server factory
│   ├── tools/
│   │   └── download-image.ts # Tool implementation
│   ├── services/
│   │   ├── figma-api.ts      # Figma API client
│   │   └── image-processor.ts# Image download & encoding
│   └── types/
│       └── figma.ts          # TypeScript type definitions
├── dist/                     # Compiled JavaScript (generated)
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

Deployment

The server is deployed to Azure Web App with automatic GitHub Actions CI/CD.

Deployment URL

Live: https://tr-figma-mcpserver-gsakbybcgegzdkc4.centralus-01.azurewebsites.net

Endpoints

• Health Check: /health

• MCP SSE: /mcp

• Info: /

GitHub Actions

Every push to main or master branch triggers automatic deployment:

1. Install dependencies

2. Build TypeScript

3. Run type checking

4. Deploy to Azure Web App

5. Verify deployment with health check

Monitor deployments at: GitHub Actions

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues

• MCP Documentation: Model Context Protocol

• Figma API: Figma Developer Docs

• Service Status: https://tr-figma-mcpserver-gsakbybcgegzdkc4.centralus-01.azurewebsites.net/health

Acknowledgments

• Built with Model Context Protocol SDK

• Powered by Figma API

• Hosted on Azure Web App

Made with ❤️ by Thomson Reuters

Live Service: https://tr-figma-mcpserver-gsakbybcgegzdkc4.centralus-01.azurewebsites.net