Skip to content
Back to search

figma-mcp-server

Model Context Protocol server implementation for Figma API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/timholden--figma-mcp-server/badge.svg)](/listings/timholden--figma-mcp-server)

HTML

<a href="/listings/timholden--figma-mcp-server"><img src="/api/listings/timholden--figma-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install figma-mcp-server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 279 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Figma MCP Server
  2. A Model Context Protocol (MCP) server that provides integration with Figma's API through Claude and other MCP-compatible clients. Currently supports read-only access to Figma files and projects, with server-side architecture capable of supporting more advanced design token and theme management features (pending Figma API enhancements or plugin development).
  3. ## Project Status
  4. ### Current Progress
  5. - ✅ **Core Implementation**: Successfully built a TypeScript server following the Model Context Protocol (MCP)
  6. - ✅ **Claude Desktop Integration**: Tested and functional with Claude Desktop
  7. - ✅ **Read Operations**: Working `get-file` and `list-files` tools for Figma file access
  8. - ✅ **Server Architecture**: Caching system, error handling, and stats monitoring implemented
  9. - ✅ **Transport Protocols**: Both stdio and SSE transport mechanisms supported
  10. ### Potential Full Functionality
  11. The server has been designed with code to support these features (currently limited by API restrictions):
  12. - **Variable Management**: Create, read, update, and delete design tokens (variables)
  13. - **Reference Handling**: Create and validate relationships between tokens
  14. - **Theme Management**: Create themes with multiple modes (e.g., light/dark)
  15. - **Dependency Analysis**: Detect and prevent circular references
  16. - **Batch Operations**: Perform bulk actions on variables and themes
  17. With Figma plugin development or expanded API access, these features could be fully enabled.
  18. ## Features
  19. - 🔑 Secure authentication with Figma API
  20. - 📁 File operations (read, list)
  21. - 🎨 Design system management
  22. - Variable creation and management
  23. - Theme creation and configuration
  24. - Reference handling and validation
  25. - 🚀 Performance optimized
  26. - LRU caching
  27. - Rate limit handling
  28. - Connection pooling
  29. - 📊 Comprehensive monitoring
  30. - Health checks
  31. - Usage statistics
  32. - Error tracking
  33. ## Prerequisites
  34. - Node.js 18.x or higher
  35. - Figma access token with appropriate permissions
  36. - Basic understanding of MCP (Model Context Protocol)
  37. ## Installation
  38. ```bash
  39. npm install figma-mcp-server
  40. ```
  41. ## Configuration
  42. 1. Create a `.env` file based on `.env.example`:
  43. ```env
  44. # Figma API Access Token
  45. FIGMA_ACCESS_TOKEN=your_figma_token
  46. # Server Configuration
  47. MCP_SERVER_PORT=3000
  48. # Debug Configuration
  49. DEBUG=figma-mcp:*
  50. ```
  51. 2. For Claude Desktop integration:
  52. The server can be configured in your Claude Desktop config file:
  53. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  54. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  55. ```json
  56. {
  57. "mcpServers": {
  58. "figma": {
  59. "command": "node",
  60. "args": ["/ABSOLUTE/PATH/TO/figma-mcp-server/dist/index.js"],
  61. "env": {
  62. "FIGMA_ACCESS_TOKEN": "your_token_here"
  63. }
  64. }
  65. }
  66. }
  67. ```
  68. **Important Notes:**
  69. - Use ABSOLUTE paths, not relative paths
  70. - On Windows, use double backslashes (\\\\) in paths
  71. - Restart Claude Desktop after making configuration changes
  72. ## Usage
  73. ### Basic Usage
  74. ```javascript
  75. import { startServer } from 'figma-mcp-server';
  76. const server = await startServer(process.env.FIGMA_ACCESS_TOKEN);
  77. ```
  78. ### Available Tools
  79. 1. **get-file**
  80. - Retrieve Figma file details
  81. ```javascript
  82. {
  83. "name": "get-file",
  84. "arguments": {
  85. "fileKey": "your_file_key"
  86. }
  87. }
  88. ```
  89. 2. **list-files**
  90. - List files in a Figma project
  91. ```javascript
  92. {
  93. "name": "list-files",
  94. "arguments": {
  95. "projectId": "your_project_id"
  96. }
  97. }
  98. ```
  99. 3. **create-variables**
  100. - Create design system variables
  101. ```javascript
  102. {
  103. "name": "create-variables",
  104. "arguments": {
  105. "fileKey": "your_file_key",
  106. "variables": [
  107. {
  108. "name": "primary-color",
  109. "type": "COLOR",
  110. "value": "#0066FF"
  111. }
  112. ]
  113. }
  114. }
  115. ```
  116. 4. **create-theme**
  117. - Create and configure themes
  118. ```javascript
  119. {
  120. "name": "create-theme",
  121. "arguments": {
  122. "fileKey": "your_file_key",
  123. "name": "Dark Theme",
  124. "modes": [
  125. {
  126. "name": "dark",
  127. "variables": [
  128. {
  129. "variableId": "123",
  130. "value": "#000000"
  131. }
  132. ]
  133. }
  134. ]
  135. }
  136. }
  137. ```
  138. ## API Documentation
  139. ### Server Methods
  140. - `startServer(figmaToken: string, debug?: boolean, port?: number)`
  141. - Initializes and starts the MCP server
  142. - Returns: Promise<MCPServer>
  143. ### Tool Schemas
  144. All tool inputs are validated using Zod schemas:
  145. ```typescript
  146. const CreateVariablesSchema = z.object({
  147. fileKey: z.string(),
  148. variables: z.array(z.object({
  149. name: z.string(),
  150. type: z.enum(['COLOR', 'FLOAT', 'STRING']),
  151. value: z.string(),
  152. scope: z.enum(['LOCAL', 'ALL_FRAMES'])
  153. }))
  154. });
  155. ```
  156. ## Error Handling
  157. The server provides detailed error messages and proper error codes:
  158. - Invalid token: 403 with specific error message
  159. - Rate limiting: 429 with reset time
  160. - Validation errors: 400 with field-specific details
  161. - Server errors: 500 with error tracking
  162. ## Limitations & Known Issues
  163. ### API Restrictions
  164. 1. **Read-Only Operations**
  165. - Limited to read-only operations due to Figma API restrictions
  166. - Personal access tokens only support read operations, not write
  167. - Cannot modify variables, components, or styles through REST API with personal tokens
  168. - Write operations would require Figma plugin development instead
  169. 2. **Rate Limiting**
  170. - Follows Figma API rate limits
  171. - Implement exponential backoff for better handling
  172. 3. **Cache Management**
  173. - Default 5-minute TTL
  174. - Limited to 500 entries
  175. - Consider implementing cache invalidation hooks
  176. 4. **Authentication**
  177. - Only supports personal access tokens
  178. - No support for team-level permissions or collaborative editing
  179. - OAuth implementation planned for future
  180. 5. **Technical Implementation**
  181. - Requires absolute paths in configuration
  182. - Must compile TypeScript files before execution
  183. - Requires handling both local and global module resolution
  184. ## Contributing
  185. 1. Fork the repository
  186. 2. Create a feature branch
  187. 3. Make your changes with tests
  188. 4. Submit a pull request
  189. Please follow our coding standards:
  190. - TypeScript strict mode
  191. - ESLint configuration
  192. - Jest for testing
  193. - Comprehensive error handling
  194. ## License
  195. MIT License - See LICENSE file for details
  196. ## Troubleshooting
  197. See [TROUBLESHOOTING.md](examples/TROUBLESHOOTING.md) for a comprehensive troubleshooting guide.
  198. ### Common Issues
  199. 1. **JSON Connection Errors**
  200. - Use absolute paths in Claude Desktop configuration
  201. - Ensure the server is built (`npm run build`)
  202. - Verify all environment variables are set
  203. 2. **Authentication Issues**
  204. - Verify your Figma access token is valid
  205. - Check the token has required permissions
  206. - Ensure the token is correctly set in configuration
  207. 3. **Server Not Starting**
  208. - Check Node.js version (18.x+ required)
  209. - Verify the build exists (`dist/index.js`)
  210. - Check Claude Desktop logs:
  211. - macOS: `~/Library/Logs/Claude/mcp*.log`
  212. - Windows: `%APPDATA%\Claude\logs\mcp*.log`
  213. For more detailed debugging steps and solutions, refer to the troubleshooting guide.
  214. ## Support
  215. - GitHub Issues: [Report a bug](https://github.com/your-repo/issues)
  216. - Documentation: [Wiki](https://github.com/your-repo/wiki)
  217. - Discord: [Join our community](https://discord.gg/your-server)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.