Configuration

This page documents all configuration options available in the Framelink MCP for Figma. Configuration can be provided via CLI arguments or environment variables.

CLI Arguments

All CLI arguments can be passed when starting the server.

--figma-api-key

Your Figma API key (Personal Access Token). This is the recommended authentication method for most users.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx

--figma-oauth-token

Figma OAuth Bearer token. Use this if you're authenticating via OAuth instead of a Personal Access Token.

npx figma-developer-mcp --figma-oauth-token=your-oauth-token

--env

Path to a custom .env file to load environment variables from. If not specified, the server looks for a .env file in the current working directory.

npx figma-developer-mcp --env=/path/to/custom/.env

--stdio

Run the server in stdio transport mode. Use this flag for local MCP client integrations (Cursor, Claude Desktop, Windsurf, and similar) that launch the server as a subprocess and communicate over stdin/stdout. Without this flag, the server starts an HTTP server on the configured port instead.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --stdio

--port

Port to run the HTTP server on. Only applies when running in HTTP/SSE mode (not stdio). Defaults to 3333.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --port=8080

--host

Host address to bind the HTTP server to. Only applies when running in HTTP/SSE mode (not stdio). Defaults to 127.0.0.1.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --host=0.0.0.0

--format

Output format for design data returned by tools. Defaults to yaml.

• yaml — default; fewer tokens than JSON for typical designs.
• json — useful when piping output into tools that expect JSON.
• tree — experimental compact format. Structural keys (id, name, type) are encoded positionally on each node line, and style values stay deduplicated in a globalVars block. Designs with heavy style reuse see the largest token savings.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --format=tree --stdio

--json

Back-compat alias for --format=json. Prefer --format for new configs.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --json

--image-dir

Base directory for image downloads. The download_figma_images tool will only write files within this directory. Defaults to the current working directory. The tool description shown to AI agents includes this path so they know where to save images.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --image-dir=/path/to/project

--proxy

HTTP proxy URL for networks that require outbound traffic to go through a proxy server. The server also automatically respects the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables when they are available.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --proxy=http://proxy.example.com:8080

Pass --proxy=none to explicitly ignore any proxy environment variables and connect directly. Useful when a system-level proxy is misbehaving for api.figma.com specifically and you can't easily unset the environment variable.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --proxy=none --stdio

See the network proxy troubleshooting guide for more details.

--skip-image-downloads

Disable the download_figma_images tool. When set, the server will not register the image download tool, which can be useful if you don't need image export functionality.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --skip-image-downloads

--no-telemetry

Disables anonymous usage telemetry. The server normally sends one event per tool call describing timing, response shape, and any errors (with Figma credentials scrubbed) so we can prioritize improvements. This flag, FRAMELINK_TELEMETRY=off, or DO_NOT_TRACK=1 all turn it off.

npx figma-developer-mcp --figma-api-key=figd_xxxxxx --no-telemetry

--help

Display the help menu with all available options.

npx figma-developer-mcp --help

--version

Display the current version of the MCP server.

npx figma-developer-mcp --version

Environment Variables

All configuration options can also be set via environment variables. These can be defined in a .env file or set directly in your shell environment.

Note: PORT is also supported as an alias for FRAMELINK_PORT for backwards compatibility.

The server also automatically respects the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables when they are available in the server process.

Example .env file

FIGMA_API_KEY=figd_xxxxxxxxxxxxxxxxxxxxxx
FRAMELINK_PORT=3333
FRAMELINK_HOST=127.0.0.1
OUTPUT_FORMAT=yaml
SKIP_IMAGE_DOWNLOADS=false

Authentication

The MCP server supports two authentication methods for the Figma API.

Personal Access Token (Recommended)

Personal Access Tokens are the simplest way to authenticate. Generate one from your Figma account settings under Settings > Security > Personal access tokens.

Required permissions:

• File content: Read access
• Dev resources: Read access

Use via CLI argument:

--figma-api-key=figd_xxxxxx

Or via environment variable:

FIGMA_API_KEY=figd_xxxxxx

OAuth Bearer Token

For applications using Figma's OAuth flow, you can provide an OAuth bearer token instead.

Use via CLI argument:

--figma-oauth-token=your-oauth-token

Or via environment variable:

FIGMA_OAUTH_TOKEN=your-oauth-token

When an OAuth token is provided, the server uses the Authorization: Bearer header instead of the X-Figma-Token header.

Per-Request Token (HTTP mode only)

When running in HTTP/SSE mode, clients can supply a Figma Personal Access Token on each request via the X-Figma-Token header. This is useful for centrally managed deployments — an IT or platform team can run one vetted instance behind their proxy and logging while each user still authenticates with their own Figma identity, without resorting to a shared service-account token.

POST /mcp HTTP/1.1
X-Figma-Token: figd_xxxxxx

A request header takes precedence over FIGMA_API_KEY and FIGMA_OAUTH_TOKEN for that request only. If the header is absent, the server falls back to its configured global credentials.

The server can also be started in HTTP mode with no credentials configured — in that case every request must include X-Figma-Token, or the tool call will fail. Stdio mode and the fetch CLI have no per-request channel and still require credentials at startup.

Configuration Precedence

When the same option is specified in multiple places, CLI arguments take precedence over environment variables.

1. CLI arguments (highest priority)
2. Environment variables (from .env file or shell)
3. Default values (lowest priority)

For example, if you have FRAMELINK_PORT=8080 in your .env file but run the server with --port=3000, the server will use port 3000.

For Figma authentication specifically, a per-request X-Figma-Token header on an HTTP request takes precedence over both CLI arguments and environment variables for that request only. See Per-Request Token.