figma-mcp-server 0.1.0-beta.1 → 0.1.1

package/README.md

@@ -1,63 +1,52 @@
 # Figma MCP Server
-MCP server for Figma
+A simple MCP server for Figma
 
-### Set tool environment variables
-In the `.env` file, set the `FIGMA_API_KEY` to your Figma API key.
-
-```
-FIGMA_API_KEY=
-```
-
-### Install
+## Install
 Install the server
 
-```sh
+```bash
 git clone https://github.com/planetabhi/figma-mcp-server.git
 cd figma-mcp-server
 pnpm i
 ```
 
-### List Figma Tools
-List descriptions and parameters from all available Figma tools
+### Set tool environment variable
+Create a `.env` file and set the `FIGMA_API_KEY` to your Figma API key.
 
-```sh
-pnpm list-tools
+```bash
+FIGMA_API_KEY=
 ```
 
-## Run the MCP Server
-
-The MCP Server (`mcpServer.js`) exposes your Figma API tools to MCP-compatible clients.
-
-### Run with Postman
-
-Postman desktop app is the easiest way to run and test MCP servers.
+> To generate a new personal access token, log in to your Figma account, then from the top-left menu, head to Settings, click on the security tab, find the Personal access tokens section, and click Generate new token to open the configuration modal where you can set the expiration and scopes before clicking Generate token.
 
-Step 1: Download the latest Postman app from [https://www.postman.com/downloads/](https://www.postman.com/downloads/).
+### List All Tools
+List descriptions and parameters from all available tools
 
-Step 2: Read out the documentation article [here](https://learning.postman.com/docs/postman-ai-agent-builder/mcp-requests/overview/) for the next steps.
-
-### Run with Claude Desktop
+```bash
+pnpm list-tools
+```
 
-To integrate with Claude Desktop:
+## Run the MCP Server
 
-1. Find node path:
+### Find node and server path
 
-```sh
+```bash
+# Find node path
 which node
-```
-
-2. Find `mcpServer.js` path:
 
-```sh
+# Get the absolute path of the MCP server
 realpath mcpServer.js
 ```
 
-3. Open Claude Desktop → **Settings** → **Developers** → **Edit Config** and add your server:
+
+### Run with Claude Desktop
+
+1. Open Claude Desktop → **Settings** → **Developers** → **Edit Config** and add your server:
 
 ```json
 {
   "mcpServers": {
-    "<server_name>": {
+    "figma-mcp-server": {
       "command": "<absolute_path_to_node>",
       "args": ["<absolute_path_to_mcpServer.js>"]
     }
@@ -65,41 +54,59 @@ realpath mcpServer.js
 }
 ```
 
-Restart Claude Desktop to activate this change.
+2. Restart Claude Desktop to activate config change.
+
+> To try it out in Claude Desktop, first enable the `get_file_nodes` tool from the tools list. Copy a design node link from a Figma file, then paste it into Claude Desktop prompt. It will return the design node data and other information.
+
+### Run in Postman
+
+1. Choose an existing workspace or create a new one.
+2. Select New > MCP. Postman opens a new MCP request in a new tab.
+3. Select the server's communication method STDIO.
+4. Enter the server's command and arguments.
+
+```bash
+# Create a new MCP request and add the server's command and arguments
+STDIO <absolute_path_to_node> <absolute_path_to_mcpServer.js>
+```
+
+> [Postman collection](https://www.postman.com/doitagain/workspace/figma/collection/68369062465421c338809955?action=share&creator=17652550).
+
+---
 
-### Additional Options
+### Misc
 
-#### Docker Deployment (Production)
+#### Docker Deployment
 
 For production deployments, you can use Docker:
 
 **1. Build Docker image**
 
-```sh
-docker build -t <your_server_name> .
+```bash
+docker build -t figma-mcp-server .
 ```
 
-**2. Claude Desktop Integration**
+**2. Claude Desktop integration**
 
 Add Docker server configuration to Claude Desktop (Settings → Developers → Edit Config):
 
 ```json
 {
   "mcpServers": {
-    "<your_server_name>": {
+    "figma-mcp-server": {
       "command": "docker",
-      "args": ["run", "-i", "--rm", "--env-file=.env", "<your_server_name>"]
+      "args": ["run", "-i", "--rm", "--env-file=.env", "figma-mcp-server"]
     }
   }
 }
 ```
 
-> Add your environment variables (API keys, etc.) inside the `.env` file.
+> Add your environment variables inside the `.env` file.
 
 #### Server-Sent Events (SSE)
 
 To run the server with Server-Sent Events (SSE) support, use the `--sse` flag:
 
-```sh
+```bash
 node mcpServer.js --sse
 ```

package/mcpServer.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 import dotenv from "dotenv";
 import express from "express";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -36,32 +37,7 @@ async function transformTools(tools) {
     .filter(Boolean);
 }
 
-async function run() {
-  const args = process.argv.slice(2);
-  const isSSE = args.includes("--sse");
-
-  const server = new Server(
-    {
-      name: SERVER_NAME,
-      version: "0.1.0",
-    },
-    {
-      capabilities: {
-        tools: {},
-      },
-    }
-  );
-
-  server.onerror = (error) => console.error("[Error]", error);
-
-  // Gracefully shutdown on SIGINT
-  process.on("SIGINT", async () => {
-    await server.close();
-    process.exit(0);
-  });
-
-  const tools = await discoverTools();
-
+async function setupServerHandlers(server, tools) {
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: await transformTools(tools),
   }));
@@ -69,15 +45,12 @@ async function run() {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const toolName = request.params.name;
     const tool = tools.find((t) => t.definition.function.name === toolName);
-
     if (!tool) {
       throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${toolName}`);
     }
-
     const args = request.params.arguments;
     const requiredParameters =
       tool.definition?.function?.parameters?.required || [];
-
     for (const requiredParameter of requiredParameters) {
       if (!(requiredParameter in args)) {
         throw new McpError(
@@ -86,7 +59,6 @@ async function run() {
         );
       }
     }
-
     try {
       const result = await tool.function(args);
       return {
@@ -105,17 +77,42 @@ async function run() {
       );
     }
   });
+}
+
+async function run() {
+  const args = process.argv.slice(2);
+  const isSSE = args.includes("--sse");
+  const tools = await discoverTools();
 
   if (isSSE) {
     const app = express();
     const transports = {};
+    const servers = {};
 
     app.get("/sse", async (_req, res) => {
+      // Create a new Server instance for each session
+      const server = new Server(
+        {
+          name: SERVER_NAME,
+          version: "0.1.0",
+        },
+        {
+          capabilities: {
+            tools: {},
+          },
+        }
+      );
+      server.onerror = (error) => console.error("[Error]", error);
+      await setupServerHandlers(server, tools);
+
       const transport = new SSEServerTransport("/messages", res);
       transports[transport.sessionId] = transport;
+      servers[transport.sessionId] = server;
 
-      res.on("close", () => {
+      res.on("close", async () => {
         delete transports[transport.sessionId];
+        await server.close();
+        delete servers[transport.sessionId];
       });
 
       await server.connect(transport);
@@ -124,11 +121,12 @@ async function run() {
     app.post("/messages", async (req, res) => {
       const sessionId = req.query.sessionId;
       const transport = transports[sessionId];
+      const server = servers[sessionId];
 
-      if (transport) {
+      if (transport && server) {
         await transport.handlePostMessage(req, res);
       } else {
-        res.status(400).send("No transport found for sessionId");
+        res.status(400).send("No transport/server found for sessionId");
       }
     });
 
@@ -137,6 +135,26 @@ async function run() {
       console.log(`[SSE Server] running on port ${port}`);
     });
   } else {
+    // stdio mode: single server instance
+    const server = new Server(
+      {
+        name: SERVER_NAME,
+        version: "0.1.0",
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+    server.onerror = (error) => console.error("[Error]", error);
+    await setupServerHandlers(server, tools);
+
+    process.on("SIGINT", async () => {
+      await server.close();
+      process.exit(0);
+    });
+
     const transport = new StdioServerTransport();
     await server.connect(transport);
   }

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "figma-mcp-server",
-  "version": "0.1.0-beta.1",
-  "description": "MCP server for Figma",
+  "version": "0.1.1",
+  "description": "A simple MCP server for Figma",
   "main": "index.js",
   "type": "module",
   "scripts": {
     "list-tools": "node index.js tools"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
     "commander": "^14.0.0",
     "dotenv": "^16.5.0",
     "express": "^5.1.0"

package/tools/figma/figma-api/create-dev-resources-for-a-file.js

@@ -0,0 +1,95 @@
+/**
+ * Function to create development resources for a Figma file.
+ *
+ * @param {Object} args - Arguments for creating development resources.
+ * @param {string} args.file_key - The key of the Figma file.
+ * @param {string} args.node_id - The node ID for the resource.
+ * @param {string} args.name - The name of the development resource.
+ * @param {string} args.url - The URL for the development resource.
+ * @returns {Promise<Object>} - The result of the resource creation.
+ */
+const executeFunction = async ({ file_key, node_id, name, url }) => {
+  const baseUrl = 'https://api.figma.com';
+  const token = process.env.FIGMA_API_KEY;
+  try {
+    // Construct the URL for the API request
+    const url = `${baseUrl}/v1/files/${file_key}/dev_resources`;
+
+    // Set up headers for the request
+    const headers = {
+      'X-Figma-Token': token,
+      'Content-Type': 'application/json'
+    };
+
+    // Create the body for the request
+    const body = JSON.stringify({
+      dev_resources: [
+        {
+          name,
+          url,
+          file_key,
+          node_id
+        }
+      ]
+    });
+
+    // Perform the fetch request
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body
+    });
+
+    // Check if the response was successful
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData);
+    }
+
+    // Parse and return the response data
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    console.error('Error creating development resources:', error);
+    return { error: 'An error occurred while creating development resources.' };
+  }
+};
+
+/**
+ * Tool configuration for creating development resources for a Figma file.
+ * @type {Object}
+ */
+const apiTool = {
+  function: executeFunction,
+  definition: {
+    type: 'function',
+    function: {
+      name: 'create_dev_resources',
+      description: 'Create development resources for a Figma file.',
+      parameters: {
+        type: 'object',
+        properties: {
+          file_key: {
+            type: 'string',
+            description: 'The key of the Figma file.'
+          },
+          node_id: {
+            type: 'string',
+            description: 'The node ID for the resource.'
+          },
+          name: {
+            type: 'string',
+            description: 'The name of the development resource.'
+          },
+          url: {
+            type: 'string',
+            description: 'The URL for the development resource.'
+          }
+        },
+        required: ['file_key', 'node_id', 'name', 'url']
+      }
+    }
+  }
+};
+
+export { apiTool };

package/tools/figma/figma-api/{create-variable-collection.js → create-variable-collections-for-a-file.js}

@@ -1,18 +1,17 @@
 /**
- * Function to create a variable collection in Figma.
+ * Function to create variable collections for a Figma file.
  *
- * @param {Object} args - Arguments for creating the variable collection.
+ * @param {Object} args - Arguments for creating variable collections.
  * @param {string} args.file_key - The key of the Figma file where the variable collection will be created.
- * @param {string} args.name - The name of the new variable collection to be created.
+ * @param {string} args.name - The name of the variable collection to create.
  * @returns {Promise<Object>} - The result of the variable collection creation.
  */
 const executeFunction = async ({ file_key, name }) => {
-  const baseUrl = 'https://api.figma.com/v1';
+  const baseUrl = 'https://api.figma.com';
   const token = process.env.FIGMA_API_KEY;
-
   try {
     // Construct the URL for the request
-    const url = `${baseUrl}/files/${file_key}/variables`;
+    const url = `${baseUrl}/v1/files/${file_key}/variables`;
 
     // Set up headers for the request
     const headers = {
@@ -20,7 +19,7 @@ const executeFunction = async ({ file_key, name }) => {
       'Content-Type': 'application/json'
     };
 
-    // Create the request body
+    // Define the body of the request
     const body = JSON.stringify({
       variableCollections: [
         {
@@ -47,13 +46,13 @@ const executeFunction = async ({ file_key, name }) => {
     const data = await response.json();
     return data;
   } catch (error) {
-    console.error('Error creating variable collection:', error);
-    return { error: 'An error occurred while creating the variable collection.' };
+    console.error('Error creating variable collections:', error);
+    return { error: 'An error occurred while creating variable collections.' };
   }
 };
 
 /**
- * Tool configuration for creating a variable collection in Figma.
+ * Tool configuration for creating variable collections in a Figma file.
  * @type {Object}
  */
 const apiTool = {
@@ -61,8 +60,8 @@ const apiTool = {
   definition: {
     type: 'function',
     function: {
-      name: 'create_variable_collection',
-      description: 'Create a new variable collection in Figma.',
+      name: 'create_variable_collections',
+      description: 'Create variable collections for a Figma file.',
       parameters: {
         type: 'object',
         properties: {
@@ -72,7 +71,7 @@ const apiTool = {
           },
           name: {
             type: 'string',
-            description: 'The name of the new variable collection to be created.'
+            description: 'The name of the variable collection to create.'
           }
         },
         required: ['file_key', 'name']

package/tools/figma/figma-api/get-a-published-component-by-key.js

@@ -0,0 +1,66 @@
+/**
+ * Function to get metadata for a published component in Figma by its key.
+ *
+ * @param {Object} args - Arguments for the request.
+ * @param {string} args.key - The key of the component to retrieve.
+ * @returns {Promise<Object>} - The metadata of the published component.
+ */
+const executeFunction = async ({ key }) => {
+  const baseUrl = 'https://api.figma.com/v1/components';
+  const token = process.env.FIGMA_API_KEY;
+  try {
+    // Construct the URL with the component key
+    const url = `${baseUrl}/${key}`;
+
+    // Set up headers for the request
+    const headers = {
+      'X-Figma-Token': token
+    };
+
+    // Perform the fetch request
+    const response = await fetch(url, {
+      method: 'GET',
+      headers
+    });
+
+    // Check if the response was successful
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData);
+    }
+
+    // Parse and return the response data
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    console.error('Error retrieving component metadata:', error);
+    return { error: 'An error occurred while retrieving component metadata.' };
+  }
+};
+
+/**
+ * Tool configuration for retrieving component metadata from Figma.
+ * @type {Object}
+ */
+const apiTool = {
+  function: executeFunction,
+  definition: {
+    type: 'function',
+    function: {
+      name: 'get_published_component_by_key',
+      description: 'Retrieve metadata for a published component by its key.',
+      parameters: {
+        type: 'object',
+        properties: {
+          key: {
+            type: 'string',
+            description: 'The key of the component to retrieve.'
+          }
+        },
+        required: ['key']
+      }
+    }
+  }
+};
+
+export { apiTool };

package/tools/figma/figma-api/get-a-published-component-set-by-key.js

@@ -0,0 +1,66 @@
+/**
+ * Function to get metadata for a published component set by its key from Figma.
+ *
+ * @param {Object} args - Arguments for the request.
+ * @param {string} args.key - The key of the component set to retrieve.
+ * @returns {Promise<Object>} - The metadata for the component set.
+ */
+const executeFunction = async ({ key }) => {
+  const baseUrl = 'https://api.figma.com';
+  const token = process.env.FIGMA_API_KEY;
+  try {
+    // Construct the URL with the component set key
+    const url = `${baseUrl}/v1/component_sets/${key}`;
+
+    // Set up headers for the request
+    const headers = {
+      'X-Figma-Token': token
+    };
+
+    // Perform the fetch request
+    const response = await fetch(url, {
+      method: 'GET',
+      headers
+    });
+
+    // Check if the response was successful
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData);
+    }
+
+    // Parse and return the response data
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    console.error('Error retrieving component set metadata:', error);
+    return { error: 'An error occurred while retrieving component set metadata.' };
+  }
+};
+
+/**
+ * Tool configuration for retrieving component set metadata from Figma.
+ * @type {Object}
+ */
+const apiTool = {
+  function: executeFunction,
+  definition: {
+    type: 'function',
+    function: {
+      name: 'get_component_set',
+      description: 'Retrieve metadata for a published component set by its key.',
+      parameters: {
+        type: 'object',
+        properties: {
+          key: {
+            type: 'string',
+            description: 'The key of the component set to retrieve.'
+          }
+        },
+        required: ['key']
+      }
+    }
+  }
+};
+
+export { apiTool };

package/tools/figma/figma-api/get-a-published-library-by-id.js

@@ -0,0 +1,66 @@
+/**
+ * Function to get metadata for a published library in Figma by its ID.
+ *
+ * @param {Object} args - Arguments for the library retrieval.
+ * @param {string} args.library_id - The ID of the library to retrieve.
+ * @returns {Promise<Object>} - The metadata of the published library.
+ */
+const executeFunction = async ({ library_id }) => {
+  const baseUrl = 'https://api.figma.com';
+  const token = process.env.FIGMA_API_KEY;
+  try {
+    // Construct the URL with the library ID
+    const url = `${baseUrl}/v1/libraries/${library_id}`;
+
+    // Set up headers for the request
+    const headers = {
+      'X-Figma-Token': token
+    };
+
+    // Perform the fetch request
+    const response = await fetch(url, {
+      method: 'GET',
+      headers
+    });
+
+    // Check if the response was successful
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData);
+    }
+
+    // Parse and return the response data
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    console.error('Error retrieving library metadata:', error);
+    return { error: 'An error occurred while retrieving library metadata.' };
+  }
+};
+
+/**
+ * Tool configuration for retrieving library metadata in Figma.
+ * @type {Object}
+ */
+const apiTool = {
+  function: executeFunction,
+  definition: {
+    type: 'function',
+    function: {
+      name: 'get_library_by_id',
+      description: 'Retrieve metadata for a published library by its ID.',
+      parameters: {
+        type: 'object',
+        properties: {
+          library_id: {
+            type: 'string',
+            description: 'The ID of the library to retrieve.'
+          }
+        },
+        required: ['library_id']
+      }
+    }
+  }
+};
+
+export { apiTool };