Google Fonts MCP

MCP server and Claude Code skill for typography system generation using Google Fonts. Searches 1,923 enriched fonts, suggests singles or pairs, and generates complete CSS/Tailwind typographic systems.

What It Does

• Font search with BM25 ranking across personality, mood, and use-case tags
• Single font mode — one font for heading + body (body-suitable, multi-weight)
• Pair mode — 73 proven pairings with contrast type classification
• CSS generation — custom properties, Tailwind config, Google Fonts embed links
• 8 modular scales — from minor-second (dense UI) to golden-ratio (hero sections)
• 100-project showcase — browsable gallery of pre-made typography systems

How It Works

1. Tell Claude what you're building (SaaS, blog, e-commerce...)
2. Skill searches 1,923 fonts or 73 proven pairings
3. Pick a font + scale → get CSS custom properties, Tailwind config, and embed link
4. Ship

Installation

MCP Server (any agent)

uvx google-fonts-mcp

Or install permanently:

pip install google-fonts-mcp

Claude Code

claude mcp add google-fonts -- uvx google-fonts-mcp

Or as a plugin:

claude plugin marketplace add sliday/google-fonts-skill
claude plugin install google-fonts

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "google-fonts": {
      "command": "uvx",
      "args": ["google-fonts-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "google-fonts": {
      "command": "uvx",
      "args": ["google-fonts-mcp"]
    }
  }
}

Any MCP Client

{
  "command": "uvx",
  "args": ["google-fonts-mcp"]
}

Usage

The skill activates automatically when you mention fonts, typography, or type scales in Claude Code.

CLI Scripts

# Search for a single body-suitable font
python3 scripts/search.py "modern clean SaaS" --mode single

# Search proven font pairings
python3 scripts/search.py "elegant editorial luxury" --mode pair

# Look up a specific font
python3 scripts/search.py "Inter" --mode lookup

# Search type scales
python3 scripts/search.py "marketing bold" --mode scale

# Generate CSS + Tailwind + embed for a single font
python3 scripts/generate-css.py --font "Inter" --scale major-third --format all

# Generate for a font pair
python3 scripts/generate-css.py --heading "Playfair Display" --body "Inter" \
  --scale perfect-fourth --format all

Data

File	Records	Description
data/fonts.csv	1,923	Google Fonts with personality, contrast, body-suitability, quality tier
data/pairings.csv	73	Proven pairings with contrast type and scale recommendations
data/scales.csv	8	Modular type scales with sizes, line-heights, letter-spacing

Scale Reference

Scale	Ratio	Best For
minor-second	1.067	Dense UI, dashboards
major-second	1.125	Apps, admin panels
minor-third	1.2	General purpose
major-third	1.25	Blogs, content
perfect-fourth	1.333	Marketing, editorial
augmented-fourth	1.414	Magazines, expressive
perfect-fifth	1.5	Display-heavy
golden-ratio	1.618	Hero sections

Showcase Gallery

Browse 100 Typography Systems →

100 pre-made typography systems applied to fictional projects — SaaS dashboards, editorial blogs, luxury brands, gaming sites, and more. Each page renders live with actual Google Fonts.

Regenerate with:

python3 scripts/generate-showcase.py

MCP Tools

Tool	Description
search_fonts	Search fonts by mood/use-case. Modes: single, pair, scale
generate_typography_system	Full CSS + Tailwind + embed from font + scale
lookup_font	Get full metadata for a specific font
list_scales	All 8 typographic scales
list_pairings	All 73 proven pairings (filterable by contrast type)

Project Structure

├── src/google_fonts_mcp/             # MCP server (PyPI package)
│   ├── server.py                     # FastMCP server with 5 tools
│   ├── core.py                       # Search engine + CSS generation
│   └── data/                         # Bundled font data
├── SKILL.md                          # Claude Code skill definition
├── data/                             # Canonical font data (CSV)
├── scripts/                          # CLI tools + generators
├── showcase/                         # 100-project gallery + SEO
│   ├── llms-full.txt                 # Agent-readable full reference
│   └── pages/                        # Individual HTML previews
├── tests/                            # pytest suite
└── registry/                         # MCP registry submission files

Development

uv sync          # install deps incl. pytest (dev group)
uv run pytest -q # run the test suite

Weight strings follow the css2 API: semicolons between discrete weights (400;700), .. for variable ranges (100..900). Comma input is auto-normalized; invalid axis specifications are rejected before generating code.

License

MIT