[MCP] loadFontAsync fails for locally installed fonts

I found a reproducible issue when using Figma MCP with design system components, and I’d like to understand whether this is a known limitation or something that could be improved.

Observed behavior:
1. I can successfully find the component using search_design_system()
2. I can successfully import it using importComponentSetByKeyAsync()
3. I can successfully call createInstance()
4. But figma.currentPage.appendChild(instance) fails

Typical error:
- unloaded font "xxx Regular"
- unloaded font "xxx Bold"

So in practice:
- the component definition is accessible
- the instance can be created
- but the instance cannot actually be placed on the canvas because font validation fails at appendChild()

This creates a confusing “half-working” state where the component appears usable until the final append step.

Important details:
- The target component comes from a design system library
- The required fonts exist in the local Figma / organization environment
- But in the MCP runtime, loadFontAsync({ family: "xxx", style: "Regular" }) fails
- appendChild(instance) then fails because those fonts are unavailable in the MCP execution environment
- If I replace the text fonts inside the instance with fonts that are available in MCP, the instance can be appended successfully
- That suggests the issue is not search/import/createInstance itself, but font availability in the MCP runtime

Questions:
1. Does Figma MCP support organization shared fonts?
2. Is the MCP font environment intentionally different from the local Figma desktop environment?
3. If yes, can this be documented more explicitly?
4. Could font dependency issues be surfaced earlier, before appendChild()?
5. Could MCP provide a better fallback/degradation path, for example:
   - preflight font dependency checks
   - explicit reporting of unavailable fonts required by a component
   - an option to import structure even when fonts are missing
   - a way to specify fallback font behavior during import

Why this feels worth improving:
- From a user perspective, search/import/createInstance all succeed, so the component appears usable
- Failure only happens at appendChild(), which makes the issue harder to diagnose
- The error says fonts are unloaded, but does not clearly explain that this is an MCP runtime limitation rather than a library access issue, permission issue, or script issue

If this is a known limitation, clearer documentation would help a lot.
If it’s not, improving the preflight checks and error messaging would make the MCP workflow much more predictable.

I just ran into this today as well. And it also makes it so you can’t use an instance of a component that uses a locally installed font. Here’s a summary Claude put together:

Summary

The use_figma MCP tool executes JavaScript via the Figma Plugin API, but the plugin execution context does not have access to locally installed fonts. This causes failures for any operation that involves text nodes using non-bundled fonts, even when those fonts are installed on the system and already in use within the open Figma file.

Environment

• Tool: Figma MCP server (use_figma tool)
• Client: Claude Desktop (macOS)
• Figma file: TGLA – 2026 Design System (H6556YlsGQZRkAfoaZ6PXS)
• Fonts affected: AcuminProBook, AcuminProBold, AcuminProMedium, AcuminProSemibold
• Font location: ~/Library/Fonts (locally installed, not Adobe CC)
• OS: macOS

Observed Behaviour

1. figma.listAvailableFontsAsync() returns an empty array

const fonts = await figma.listAvailableFontsAsync();// Result: []

Expected: All locally installed fonts should be returned, matching the behaviour of a standard Figma plugin running inside the desktop app.

Actual: Returns an empty array, indicating the plugin execution context has no access to the system font service.

2. figma.loadFontAsync() fails for locally installed fonts

await figma.loadFontAsync({ family: "AcuminProBook", style: "Book" });// Error: The font "AcuminProBook Book" could not be loaded.// Please call figma.listAvailableFontsAsync() to see the list of available fonts.

All AcuminPro variants were tested and all failed:

Note: Walking the document tree confirmed these exact fonts are already used by text nodes in the open file and render correctly in the Figma desktop app.

3. ComponentNode.createInstance() fails for components containing affected fonts

const btnComponent = await figma.getNodeByIdAsync('93:2308');const instance = btnComponent.createInstance();// Error: in appendChild: unloaded font "AcuminProBook Book".// Please call figma.loadFontAsync({ family: "AcuminProBook", style: "Book" })// and await the returned promise first.

Expected: Creating an instance of an existing component (whose master already exists in the file) should not require re-loading fonts that are already present in the document.

Actual: The operation is blocked by the same font loading failure, making it impossible to programmatically instantiate any component that contains text using a locally installed font.

Impact

This combination of failures means the use_figma tool cannot:

• Create new text nodes using any locally installed font
• Instantiate existing components that contain text using locally installed fonts
• Effectively work with any design system that uses custom/local typography

Only fonts available to the plugin's restricted execution context (e.g. Inter, Roboto) can be used, which defeats the purpose of working within an established design system.

Root Cause (Hypothesis)

The use_figma tool appears to execute plugin code in a sandboxed environment that is isolated from the OS font service. A normal Figma plugin running inside the desktop app has access to ~/Library/Fonts and returns those fonts via listAvailableFontsAsync(). The MCP plugin context does not, suggesting it runs in a worker or headless context that bypasses the desktop app's font resolution path.

Steps to Reproduce

1. Install any custom font locally (e.g. to ~/Library/Fonts)
2. Open a Figma file that uses that font (confirm text nodes render correctly)
3. Via the Figma MCP use_figma tool, call figma.listAvailableFontsAsync()
4. Observe empty array returned
5. Call figma.loadFontAsync({ family: "<LocalFont>", style: "<Style>" })
6. Observe failure despite font being installed and in use in the file

Expected Behaviour

The use_figma plugin execution context should have the same font access as a standard Figma desktop plugin, including all fonts installed at the OS level (~/Library/Fonts, /Library/Fonts, etc.).

I encountered the same problem. After confirming with Claude that my local fonts were indeed installed, he concluded that the root cause was that MCP was running in a sandbox environment, which cannot access locally installed fonts, and this issue could only be resolved by Figma itself.

Below are some screenshots from the chat.

Hi there,

Thanks for the detailed feedback about using local fonts with the Figma MCP server - and thanks to everyone who chimed in with additional context!

We've passed this thread along to our internal team, and they're aware of this limitation. Let me explain how font access currently works with the Figma MCP server.

Current Figma MCP server font support:  

• Google fonts and Apple fonts included in Figma by default ✓   
• Fonts uploaded to the organization or a specific team in the organization ✓   
• Local fonts added via Figma Font Helper ✗  

The key difference is that Server-side tools like Figma MCP server can only access fonts that are uploaded to Figma's servers. Local fonts remain on your device and aren't uploaded to our servers, which is why they're not available through the Figma MCP server.

Available workarounds:  

• Use uploaded organization fonts instead of local fonts where possible (note: this is available on the Organization and Enterprise plans - learn more here)    
• Use Google fonts and Apple fonts included in Figma by default    

  
We completely understand how limiting this is, especially for design systems using CJK fonts.

Since this is a current limitation rather than a bug, I'll move this thread to "Share your feedback" so our product team can track the demand for local font support in MCP.

We're actively looking for ways to improve this experience.

Thanks for the comprehensive reports!

Hi ​@jada.gao,

Thanks for the detailed breakdown of this MCP workflow issue. I've merged your post into this related feedback thread since it's addressing the same underlying font limitation.

For questions 1 and 2 regarding MCP font support, please refer to my response above which covers the current limitations.

As for questions 3 through 5 about documentation improvements and better error handling, I'll go ahead and pass this feedback along to our team.

Thanks,

I ran into similar issues when trying to have Figma MCP skills edit our components that use Font Awesome desktop icon fonts (rendered via text layers that are locally installed OTF files). I tried everything, and it concluded that it was a limitation with the MCP.