Figma MCP Server

Instructions

Implementation Reference

• server.js:263-274 (handler)

  The handler function for the 'list_projects' tool. It fetches the list of projects for a given Figma team_id using the Figma API, processes the response, and returns both text and structured content.

  async ({ team_id, token }) => {
    token = token || process.env.FIGMA_TOKEN;
    if (!token) throw new Error('FIGMA token required (pass token or set FIGMA_TOKEN env var).');
    const res = await figmaFetch(`/teams/${team_id}/projects`, token);
    const json = await handleFigmaResponse(res);
    const projects = (json.projects || []).map(p => ({ id: p.id, name: p.name, last_modified: p.last_modified }));
    //return { projects };
    return {
      content: [{ type: 'text', text: JSON.stringify({ projects }, null, 2) }],
      structuredContent: { projects }
    };
  }

• server.js:248-262 (schema)

  Schema definition for the 'list_projects' tool, specifying input parameters (team_id required, token optional) and output structure (array of projects with id, name, optional last_modified).

  {
    title: 'List Figma projects for a team',
    description: 'Returns a list of projects for the given team id.',
    inputSchema: {
      team_id: z.string(),
      token: z.string().optional()
    },
    outputSchema: {
      projects: z.array(z.object({
        id: z.string(),
        name: z.string(),
        last_modified: z.string().optional()
      }))
    }
  },

• server.js:246-275 (registration)

  Registration of the 'list_projects' tool with the MCP server using server.registerTool, including name, schema, and handler function.

  server.registerTool(
    'list_projects',
    {
      title: 'List Figma projects for a team',
      description: 'Returns a list of projects for the given team id.',
      inputSchema: {
        team_id: z.string(),
        token: z.string().optional()
      },
      outputSchema: {
        projects: z.array(z.object({
          id: z.string(),
          name: z.string(),
          last_modified: z.string().optional()
        }))
      }
    },
    async ({ team_id, token }) => {
      token = token || process.env.FIGMA_TOKEN;
      if (!token) throw new Error('FIGMA token required (pass token or set FIGMA_TOKEN env var).');
      const res = await figmaFetch(`/teams/${team_id}/projects`, token);
      const json = await handleFigmaResponse(res);
      const projects = (json.projects || []).map(p => ({ id: p.id, name: p.name, last_modified: p.last_modified }));
      //return { projects };
      return {
        content: [{ type: 'text', text: JSON.stringify({ projects }, null, 2) }],
        structuredContent: { projects }
      };
    }
  );

• server.js:240-243 (helper)

  Helper function used by list_projects handler to handle Figma API responses and throw errors if not OK.

  function handleFigmaResponse(res) {
    if (!res.ok) throw new Error(`Figma API error ${res.status} ${res.statusText}`);
    return res.json();
  }

• server.js:27-34 (helper)

  Helper function used by list_projects handler to make authenticated requests to the Figma API.

  function figmaFetch(path, token, qs = '') {
    const url = `${FIGMA_API_BASE}${path}${qs ? `?${qs}` : ''}`;
    return fetch(url, {
      headers: {
        'X-Figma-Token': token
      }
    });
  }