[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’m using Figma MCP with /figma-use and /figma-generate-library - it is having a problem with user installed fonts.

• It can not seem to find user installed fonts in Figma
• It can not create styles based on the user installed font
• When applying a style (manually created with a user installed font) to a component the style seems applied but it displays the default font even the style has a different one.

I have tried with both Codex and Claude code - is this an issue with MCP or my Figma setup?

Thanks!

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.).

Just an update to this, apparently it is `loadFontAsync` that is having the issue loading the font.

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.

I have been running into the same issue. My entire design system uses the font “Host Grotesk” which is a google font and Claude can’t reach it. Can Figma add Host Grotesk to their catalog?

The same for me. Funny thing is that Claude said Figma has access to 7000+ fonts and Inter was not in the list of those when I asked it to replace so I could move on. Does not matter if it’s true I spent way to many attempts and tokens on this issue. Salty take but working with the Figma MCP has not been the best and it’s the reason I rolled my own skills for what I am allowd to with the API. Another issue that wont get solved because of “conflict of interest”.

I also have this issue, which severely limits the usefulness of the MCP.
Claude seems to think it’s a limitation of how the Figma MCP server runs plugin code — that it “operates in a sandboxed environment that doesn't have the same local font access as Figma's main UI.” 
Would love a fix for this!

For anyone else with this issue, looks like the question has been addressed in this thread. There’s no fix as yet
 

Hi ​@Ronan M and ​@TenTen! I moved your replies over to this thread so we can keep the whole conversation in one place, that way you’ll get notified of any updates to this thread automatically.

I’m having the same problem!! This is definitely something people are NOT saying on LinkedIn when they talk about how amazing Claude + Figma is. 

Anyone find a work around other than manually correcting everything in Figma? 

I was able to use the Figma Console plugin and Figma Bridge Developer plugin to do this. You need both running while you use CoWork.

​@Junko3 here’s a little more info when I tried another angle with Claude today. (We) concluded this outcome with a failure still

We ran several tests trying to change an FA7 Pro icon via the Figma MCP's use_figma tool and hit the same wall every time.

What works fine:
Existing FA7 Pro text nodes render correctly in Figma because the FA Desktop App exposes the font to Figma's rendering engine.

What doesn't work:
Any attempt to write to an FA7 Pro text node fails — silently, no error thrown — because the Plugin API can't load the font. figma.listAvailableFontsAsync() only returns FA 5 & 6 Free. FA7 Pro is absent, meaning loadFontAsync() will error, and any operation that internally requires a font write (including setProperties on TEXT-type component properties) is silently dropped.

Approaches tested, all blocked:

1. Edit the TEXT node characters directly → requires loadFontAsync("Font Awesome 7 Pro") → not in the loadable font list → explicit error
2. setProperties on the nested v7-icon (pro) instance → silently does nothing — changing a TEXT-type prop still triggers an internal font write
3. Detach all parent instances, then edit the text node → same result, font still can't be loaded
4. Access via exposedInstances (the correct API for nested exposed props) → v7-icon (pro) is found and accessible, setProperties is called without error, but the icon doesn't change — same silent failure

Root cause:
The Plugin API runtime has a sandboxed font model. Licensed fonts distributed via the FA Desktop App are available to Figma's own rendering engine but are not surfaced to the Plugin API layer. This is a gap between what the Figma UI can do and what plugins/MCP can do.

What would fix it:
Figma exposing locally installed licensed fonts to the Plugin API runtime, or providing a dedicated API for icon component property swaps that bypasses the font-loading requirement.

Hey ​@megaroeny! 

Thank you for detailing what you discovered trying to use your Font Awesome font with the MCP; while expected when it comes to using a local font with the MCP, noting what you tested will be helpful for others who are not aware and try any of the tests you documented. Are the other fonts you listed local-only fonts, or were those uploaded to your organization?

Uploading fonts to your organization as mentioned by ​@Junko3  is another solution you can use in the meantime.

Can confirm, uploading fonts to my org has provided a workaround and allowed the MCP to use the local fonts I needed.

​@adamsmasher We're on the Professional plan, so we can't upload to our org. 🙁

Thanks for confirming that, ​@Dan Cheng! Glad to hear that works for you as a solution.

I’m sorry to hear that, ​@megaroeny. I can see how much more of a blocker this for you. I don’t have any specifics on this particular issue, but we are actively working on the MCP - hopefully this is something we can support in a future update!