figma-mcp-server 2.0.0 → 2.1.1

package/mcpServer.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+import dotenv from "dotenv";
+import express from "express";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import {
+    CallToolRequestSchema,
+    ErrorCode,
+    ListToolsRequestSchema,
+    McpError,
+    Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import { discoverTools, type ToolWithDefinition } from "./lib/tools.ts";
+
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+dotenv.config({ path: path.resolve(__dirname, ".env") });
+
+if (!process.env.FIGMA_API_KEY) {
+    console.error("Error: FIGMA_API_KEY environment variable is required.");
+    process.exit(1);
+}
+
+const SERVER_NAME = process.env.SERVER_NAME || "figma-mcp-server";
+const SERVER_VERSION = process.env.SERVER_VERSION || "0.1.2";
+const DEFAULT_PORT = 3001;
+
+async function transformTools(tools: ToolWithDefinition[]): Promise<Tool[]> {
+    return tools
+        .map((tool) => {
+            const definitionFunction = tool.definition?.function;
+            if (!definitionFunction) return undefined;
+            return {
+                name: definitionFunction.name,
+                description: definitionFunction.description,
+                inputSchema: definitionFunction.parameters,
+            } as Tool;
+        })
+        .filter((t): t is Tool => t !== undefined);
+}
+
+async function setupServerHandlers(
+    server: Server,
+    tools: ToolWithDefinition[],
+    transformedTools: Tool[]
+) {
+    const toolMap = new Map(
+        tools.map((tool) => [tool.definition.function.name, tool])
+    );
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: transformedTools,
+    }));
+
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const toolName = request.params.name;
+        const tool = toolMap.get(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(
+                    ErrorCode.InvalidParams,
+                    `Missing required parameter: ${requiredParameter}`
+                );
+            }
+        }
+        try {
+            const result = await tool.function(args);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        } catch (error: any) {
+            console.error("[Error] Failed to fetch data:", error);
+            throw new McpError(
+                ErrorCode.InternalError,
+                `API error: ${error.message}`
+            );
+        }
+    });
+}
+
+async function run() {
+    const args = process.argv.slice(2);
+    const isSSE = args.includes("--sse");
+    const tools = await discoverTools();
+    const transformedTools = await transformTools(tools);
+
+    if (isSSE) {
+        const app = express();
+        const transports: Record<string, SSEServerTransport> = {};
+        const servers: Record<string, Server> = {};
+
+        app.get("/sse", async (_req, res) => {
+            const server = new Server(
+                {
+                    name: SERVER_NAME,
+                    version: SERVER_VERSION,
+                },
+                {
+                    capabilities: {
+                        tools: {},
+                    },
+                }
+            );
+            server.onerror = (error) => console.error("[Error]", error);
+            await setupServerHandlers(server, tools, transformedTools);
+
+            const transport = new SSEServerTransport("/messages", res);
+            transports[transport.sessionId] = transport;
+            servers[transport.sessionId] = server;
+
+            res.on("close", async () => {
+                delete transports[transport.sessionId];
+                await server.close();
+                delete servers[transport.sessionId];
+            });
+
+            await server.connect(transport);
+        });
+
+        app.post("/messages", async (req, res) => {
+            const sessionId = req.query.sessionId;
+
+            if (typeof sessionId !== "string") {
+                res.status(400).send("Invalid or missing sessionId");
+                return;
+            }
+
+            const transport = transports[sessionId];
+            const server = servers[sessionId];
+
+            if (transport && server) {
+                await transport.handlePostMessage(req, res);
+            } else {
+                res.status(400).send("No transport/server found for sessionId");
+            }
+        });
+
+        const port = process.env.PORT || DEFAULT_PORT;
+        app.listen(port, () => {
+            console.log(`[SSE Server] running on port ${port}`);
+            console.log(`[Server] Name: ${SERVER_NAME}`);
+            console.log(`[Server] Version: ${SERVER_VERSION}`);
+        });
+    } else {
+        const server = new Server(
+            {
+                name: SERVER_NAME,
+                version: SERVER_VERSION,
+            },
+            {
+                capabilities: {
+                    tools: {},
+                },
+            }
+        );
+        server.onerror = (error) => console.error("[Error]", error);
+        await setupServerHandlers(server, tools, transformedTools);
+
+        process.on("SIGINT", async () => {
+            await server.close();
+            process.exit(0);
+        });
+
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+}
+
+run().catch(console.error);

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "figma-mcp-server",
-  "version": "2.0.0",
-  "description": "A simple MCP server for Figma",
-  "main": "index.js",
+  "version": "2.1.1",
+  "description": "A comprehensive local MCP server for Figma. Connect Figma with the Gemini CLI, Cursor, and Claude Desktop.",
+  "main": "index.ts",
   "type": "module",
   "scripts": {
-    "list-tools": "node index.js tools",
-    "start": "node mcpServer.js --sse"
+    "list-tools": "bun index.ts tools",
+    "start": "bun mcpServer.ts --sse",
+    "typecheck": "bun x tsc --noEmit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "commander": "^14.0.0",
-    "dotenv": "^16.5.0",
-    "express": "^5.1.0"
+    "@clack/prompts": "^0.11.0",
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "commander": "^14.0.2",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "picocolors": "^1.1.1"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=20.0.0",
+    "bun": ">=1.1.0"
   },
   "keywords": [
     "figma",
@@ -32,5 +36,11 @@
   "bugs": {
     "url": "https://github.com/planetabhi/figma-mcp-server/issues"
   },
-  "homepage": "https://github.com/planetabhi/figma-mcp-server#readme"
-}
+  "homepage": "https://github.com/planetabhi/figma-mcp-server#readme",
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "bun-types": "^1.3.5",
+    "typescript": "^5.9.3"
+  }
+}

package/tools/figma/figma-api/{create-dev-resources-for-a-file.js → create-dev-resources-for-a-file.ts}

@@ -1,8 +1,9 @@
-const executeFunction = async ({ file_key, node_id, name, url }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ file_key, node_id, name, url }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
-    const url = `${baseUrl}/v1/files/${file_key}/dev_resources`;
+    const endpoint = `${baseUrl}/v1/files/${file_key}/dev_resources`;
 
     const headers = {
       'X-Figma-Token': token,
@@ -20,26 +21,23 @@ const executeFunction = async ({ file_key, node_id, name, url }) => {
       ]
     });
 
-    const response = await fetch(url, {
+    const response = await fetch(endpoint, {
       method: 'POST',
       headers,
       body
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     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.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

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

@@ -1,6 +1,7 @@
-const executeFunction = async ({ file_key, name }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ file_key, name }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = `${baseUrl}/v1/files/${file_key}/variables`;
 
@@ -25,19 +26,16 @@ const executeFunction = async ({ file_key, name }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     const data = await response.json();
     return data;
-  } catch (error) {
-    console.error('Error creating variable collections:', error);
-    return { error: 'An error occurred while creating variable collections.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-a-published-component-by-key.js → get-a-published-component-by-key.ts}

@@ -1,6 +1,7 @@
-const executeFunction = async ({ key }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ key }: any) => {
   const baseUrl = 'https://api.figma.com/v1/components';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = `${baseUrl}/${key}`;
 
@@ -14,19 +15,16 @@ const executeFunction = async ({ key }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     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.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-a-published-component-set-by-key.js → get-a-published-component-set-by-key.ts}

@@ -1,6 +1,7 @@
-const executeFunction = async ({ key }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ key }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = `${baseUrl}/v1/component_sets/${key}`;
 
@@ -14,19 +15,16 @@ const executeFunction = async ({ key }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     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.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-a-published-library-by-id.js → get-a-published-library-by-id.ts}

@@ -1,6 +1,7 @@
-const executeFunction = async ({ library_id }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ library_id }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = `${baseUrl}/v1/libraries/${library_id}`;
 
@@ -14,19 +15,16 @@ const executeFunction = async ({ library_id }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     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.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-a-published-style-by-key.js → get-a-published-style-by-key.ts}

@@ -1,6 +1,7 @@
-const executeFunction = async ({ key }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ key }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = `${baseUrl}/v1/styles/${key}`;
 
@@ -14,19 +15,16 @@ const executeFunction = async ({ key }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     const data = await response.json();
     return data;
-  } catch (error) {
-    console.error('Error retrieving published style:', error);
-    return { error: 'An error occurred while retrieving the published style.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-current-user.js → get-current-user.ts}

@@ -1,6 +1,7 @@
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
 const executeFunction = async () => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const headers = {
       'X-Figma-Token': token
@@ -12,19 +13,16 @@ const executeFunction = async () => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     const data = await response.json();
     return data;
-  } catch (error) {
-    console.error('Error getting current user information:', error);
-    return { error: 'An error occurred while getting user information.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-file-nodes.js → get-file-nodes.ts}

@@ -1,6 +1,7 @@
-const executeFunction = async ({ file_key, node_id }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ file_key, node_id }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = new URL(`${baseUrl}/v1/files/${file_key}/nodes`);
     if (node_id) {
@@ -17,19 +18,16 @@ const executeFunction = async ({ file_key, node_id }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     const data = await response.json();
     return data;
-  } catch (error) {
-    console.error('Error getting file nodes:', error);
-    return { error: 'An error occurred while retrieving file nodes.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-file-version-history.js → get-file-version-history.ts}

@@ -1,6 +1,7 @@
-const executeFunction = async ({ file_key }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ file_key }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = `${baseUrl}/v1/files/${file_key}/versions`;
 
@@ -14,19 +15,16 @@ const executeFunction = async ({ file_key }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     const data = await response.json();
     return data;
-  } catch (error) {
-    console.error('Error retrieving file version history:', error);
-    return { error: 'An error occurred while retrieving the file version history.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-file.js → get-file.ts}

@@ -1,6 +1,7 @@
-const executeFunction = async ({ file_key }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ file_key }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = `${baseUrl}/v1/files/${file_key}`;
 
@@ -14,19 +15,16 @@ const executeFunction = async ({ file_key }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     const data = await response.json();
     return data;
-  } catch (error) {
-    console.error('Error retrieving Figma file:', error);
-    return { error: 'An error occurred while retrieving the Figma file.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-image-fills.js → get-image-fills.ts}

@@ -1,6 +1,7 @@
-const executeFunction = async ({ file_key, node_id }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ file_key, node_id }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = new URL(`${baseUrl}/v1/images/${file_key}`);
     if (node_id) {
@@ -17,19 +18,16 @@ const executeFunction = async ({ file_key, node_id }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     const data = await response.json();
     return data;
-  } catch (error) {
-    console.error('Error getting image fills:', error);
-    return { error: 'An error occurred while getting image fills.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',

package/tools/figma/figma-api/{get-library-action-analytics.js → get-library-action-analytics.ts}

@@ -1,6 +1,7 @@
-const executeFunction = async ({ library_file_key }) => {
+import { ApiTool, getFigmaToken } from "../../../lib/tools.ts";
+const executeFunction = async ({ library_file_key }: any) => {
   const baseUrl = 'https://api.figma.com';
-  const token = process.env.FIGMA_API_KEY;
+  const token = getFigmaToken();
   try {
     const url = `${baseUrl}/v1/analytics/libraries/${library_file_key}/actions`;
 
@@ -14,19 +15,16 @@ const executeFunction = async ({ library_file_key }) => {
     });
 
     if (!response.ok) {
-      const errorData = await response.json();
-      throw new Error(errorData);
+      const errorData = await response.json() as any;
+      throw new Error(`Figma API Error: ${errorData.message || response.statusText}`);
     }
 
     const data = await response.json();
     return data;
-  } catch (error) {
-    console.error('Error retrieving library action analytics:', error);
-    return { error: 'An error occurred while retrieving library action analytics.' };
-  }
+  } catch (error) { throw error; }
 };
 
-const apiTool = {
+const apiTool: ApiTool = {
   function: executeFunction,
   definition: {
     type: 'function',