MCP server
The fontstay package includes a Model Context Protocol server. An AI agent in your editor can read your local font files, pick the fallback fonts for your audience and write the same fallback CSS as this app.
What it does
The server runs on your machine over stdio. It reads only the font files the agent names, writes nothing and makes no network requests. It is stateless: every call names its files and carries its own audience, so the agent can ask again with different options.
Tools
The server exposes four read-only tools.
analyze_font: Describes a font file: names, weight and style, detected type, vertical metrics, scripts, glyph count, variable axes, OpenType features and license.suggest_fallbacks: Lists the system font chosen as the fallback on each operating system, the audience share of each system and how much of the font’s glyph weight the fallbacks share with it.get_css: Generates the @font-face and font-family CSS, identical to the app and the command line.get_export: The same fit as CSS variables, Tailwind, Next.js, Nuxt, Astro, WordPress theme.json, Fontaine, preload tags or a loading script, with a suggested file name.
All tools except analyze_font take one to 16 font files (WOFF2, WOFF, TTF or OTF, up to 10 MB each) and the same options as the command line: audience (a Browserslist query), systems, locale, kind, unicode_range and scripts. Low glyph overlap and systems without fallback fonts come back as warnings after the result.
Setup
Add the server to your MCP client. It starts with npx and needs Node.js 24.21 or newer.
claude mcp add fontstay -- npx -y fontstay mcpConfig file: claude_desktop_config.json
{
"mcpServers": {
"fontstay": { "command": "npx", "args": ["-y", "fontstay", "mcp"] }
}
}Config file: .cursor/mcp.json
{
"mcpServers": {
"fontstay": { "command": "npx", "args": ["-y", "fontstay", "mcp"] }
}
}Config file: .vscode/mcp.json
{
"servers": {
"fontstay": { "type": "stdio", "command": "npx", "args": ["-y", "fontstay", "mcp"] }
}
}Config file: ~/.codex/config.toml
[mcp_servers.fontstay]
command = "npx"
args = ["-y", "fontstay", "mcp"]If the package is not on npm yet, build it in a checkout with pnpm cli:build and use node /path/to/packages/fontstay/dist/bin.js mcp as the command instead of npx. Relative font paths resolve against the directory the editor starts the server in.
Example prompts
Ask in plain language; the agent picks the tools.
- Analyze fonts/Inter.woff2 and tell me which scripts it covers.
- Write fallback CSS for fonts/Inter.woff2 for Windows and macOS users and add it to src/styles/fonts.css.
- Generate the Tailwind theme for my Fira Sans files, then check the warnings.
Sample result
A get_css call for tests/fixtures/fonts/FiraSans-Regular.ttf, limited to Windows and macOS, without extra script faces.
Tool call
{
"name": "get_css",
"arguments": {
"paths": ["tests/fixtures/fonts/FiraSans-Regular.ttf"],
"systems": ["windows", "macos"],
"scripts": false
}
}Result
@font-face {
font-family: "Fira Sans Fallback";
src: local("Trebuchet MS"), local("TrebuchetMS");
size-adjust: 100.3942%;
ascent-override: 93.1328%;
descent-override: 26.3959%;
line-gap-override: 0%;
}
body {
font-family: "Fira Sans", "Fira Sans Fallback", sans-serif;
/* Safari has no vertical overrides: match the x-height and fix the line box */
font-size-adjust: 0.527;
line-height: 1.4;
}
.fonts-loading {
letter-spacing: -0.0019em;
}Limits
Bad input comes back as a tool error that the agent can read and correct.
- Audience queries that load a shared config or stats file (extends, in package) are rejected.
- Windows network paths (\\host\share) are not read.
- Layout shift needs a browser and is not available; use the app for it.
- The server speaks MCP protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05, tools only.
The same engine is available as a command line tool and a Node library in the fontstay package. CLI and Node library