---
title: "Figma MCP in Cursor"
description: "Use Model Context Protocol to connect Cursor to Figma when drafting user stories: setup pattern, credentials, security, and troubleshooting."
canonical_url: "https://handbook.propay.co.za/analysis/figma-mcp"
---
# Figma MCP in Cursor

> Use Model Context Protocol to connect Cursor to Figma when drafting user stories: setup pattern, credentials, security, and troubleshooting.

## Purpose

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) lets an AI assistant in Cursor **read Figma files, frames, or design context** while you describe or refine work. That matches well with the [User story layout](https://handbook.propay.co.za/analysis/user-story-layout) and [Jira user story skill](https://handbook.propay.co.za/analysis/jira-user-story-skill): you can reference **what is in the design** without pasting large exports or screenshots for every detail.

The **exact MCP server** depends on Figma’s current API and which server implementation you use. This page describes **how to wire a server safely** in Cursor; it does not pin a single third-party package.

## Prerequisites

- A **Figma account** with access to the files or teams you need.
- **Credentials** as required by your MCP server: often a **Personal Access Token** from Figma **Settings → Security** (or OAuth, if the server supports it). See [Figma’s developer documentation](https://www.figma.com/developers/api) for API access and token scopes.
- **Cursor** with MCP support enabled (see [Cursor MCP documentation](https://cursor.com/docs/context/mcp)).

## Cursor MCP basics

1. Open **Cursor Settings** and find **MCP**, or edit your MCP config as described in the [Cursor MCP docs](https://cursor.com/docs/context/mcp).
2. Add a **server** entry:

  - **Command** and **args** as documented by the Figma MCP server you choose.
  - **Environment variables:** typically `FIGMA_*` or names the server documents (e.g. token, optional file or team id). Use **environment** or Cursor’s secret storage; never commit secrets to git.

## Server-specific setup

1. Pick an MCP server that talks to the **Figma REST API** (or the integration model your org standardizes on).
2. Create a **Figma access token** with the minimum scope needed for your workflow; paste it only into env or Cursor secrets.
3. Confirm your **file and team permissions** in Figma: the token must be able to read the files you reference.

## Security

- **Never** commit Figma tokens, `.env` files with tokens, or `mcp.json` containing secrets.
- **Rotate** tokens if they are exposed or when people leave the team.
- Prefer **read-only** or minimal scopes if the server allows it; only grant what story drafting needs.

## Troubleshooting

<table>
<thead>
  <tr>
    <th>
      Symptom
    </th>
    
    <th>
      What to check
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Connection errors
    </td>
    
    <td>
      Network, VPN, and that the MCP process can reach <code>
        api.figma.com
      </code>
      
       (or your org’s endpoint).
    </td>
  </tr>
  
  <tr>
    <td>
      403 / 404 on file
    </td>
    
    <td>
      File key or URL wrong, or your account cannot access that file.
    </td>
  </tr>
  
  <tr>
    <td>
      Stale or missing nodes
    </td>
    
    <td>
      Node id format, file version, or server cache; refresh or re-open the file in Figma.
    </td>
  </tr>
</tbody>
</table>

## Related

- [Analysis introduction](https://handbook.propay.co.za/analysis/introduction)
- [User story layout](https://handbook.propay.co.za/analysis/user-story-layout)
- [Jira user story skill](https://handbook.propay.co.za/analysis/jira-user-story-skill)
- [Jira MCP in Cursor](https://handbook.propay.co.za/analysis/jira-mcp)


## Sitemap

See the full [sitemap](https://handbook.propay.co.za/sitemap.md) for all pages.
