API Documentation

Authentication

All API endpoints (except registration) require an API key. Three methods are supported:

# Option 1: X-API-Key Header (recommended)
curl -H "X-API-Key: rf_abc123..." https://fonts.realmaker.de/v1/fonts

# Option 2: Authorization Bearer Header
curl -H "Authorization: Bearer rf_abc123..." https://fonts.realmaker.de/v1/fonts

# Option 3: Query Parameter
curl "https://fonts.realmaker.de/v1/fonts?api_key=rf_abc123..."

Endpoints

POST /v1/register

Creates a new account and returns the API key. Email and password are optional – without them, an anonymous API key is generated.

Request

POST /v1/register
Content-Type: application/json

// Minimal (anonymous API key):
{ }

// With email (key recovery possible):
{
  "email": "user@example.com",
  "password": "secure-password"
}

Response (201)

{
  "error": false,
  "message": "Registration successful. Save your API key - it will not be shown again!",
  "api_key": "rf_a1b2c3d4e5f6...",
  "api_key_prefix": "rf_a1b2",
  "tier": "free",
  "daily_limit": 100
}

GET /v1/fonts

Searches the font catalog with optional filters.

Parameters

Response

{
  "error": false,
  "fonts": [
    {
      "id": 1,
      "family": "Roboto",
      "category": "sans-serif",
      "subsets": ["latin", "latin-ext", "cyrillic"],
      "popularity": 1601,
      "variant_count": 12,
      "variants": [
        {"weight": 400, "style": "normal", "format": "woff2", "available": true}
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1601,
    "total_pages": 81
  }
}

GET /v1/css

Generates @font-face CSS code. Most important endpoint for integration.

Parameters

Response (text/css)

/* Generated by realmaker LocalFonts - DSGVO-konform */
/* Font: Roboto */

@font-face {
  font-family: 'Roboto';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url('https://deinedomain.de/v1/font/roboto/400-normal.woff2') format('woff2');
}

HTML Embedding

<link rel="stylesheet"
      href="https://deinedomain.de/v1/css?family=Roboto&weights=400,700&api_key=rf_...">

GET /v1/font/{family}/{variant}

Returns the actual font file (binary). Usually referenced automatically by the CSS.

URL Format

/v1/font/{family-slug}/{weight}-{style}.{format}

Examples:
/v1/font/roboto/400-normal.woff2
/v1/font/open-sans/700-italic.woff2
/v1/font/playfair-display/900-normal.ttf

Response: Binary font file with Cache-Control: public, max-age=31536000, immutable

GET /v1/account

Shows account information and current usage.

{
  "error": false,
  "account": {
    "email": "user@example.com",
    "tier": "free",
    "created_at": "2026-01-15 10:30:00"
  },
  "usage": {
    "requests_today": 42,
    "daily_limit": 100,
    "remaining": 58
  }
}

MCP Integration – Setup

Connect

Run this command once in your terminal. Recommended: API key as header – then it doesn't need to be specified for every tool call:

# Recommended: API key as header (configure once)claude mcp add-json rm-localfonts '{"type":"http","url":"https://fonts.realmaker.de/mcp","headers":{"X-API-Key":"rf_DEIN_KEY"}}'

# Alternative: Without header (API key per tool call)claude mcp add-json rm-localfonts '{"type":"http","url":"https://fonts.realmaker.de/mcp"}'

After that, Claude can automatically access the LocalFonts tools.

Show Tools

After setup, you can check the available tools in your browser:

# Get tools info (GET endpoint)curl https://fonts.realmaker.de/mcp

Prerequisites

• A LocalFonts API key (register for free on the homepage)
• Claude Code CLI installed
• API key via X-API-Key header (recommended) or as tool argument

MCP Protocol

realmaker LocalFonts implements the MCP HTTP Transport Protocol (JSON-RPC 2.0).

Endpoint

POST https://fonts.realmaker.de/mcp
Content-Type: application/json

Session Management

The server returns an Mcp-Session-Id header on initialize. This must be sent with all subsequent requests.

Supported Methods

Example: Initialize

# Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "clientInfo": { "name": "claude-code", "version": "1.0" }
  }
}

# Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "rm-localfonts", "version": "1.1.0" }
  }
}
# + Header: Mcp-Session-Id: abc123...

MCP Tools

All tools require a valid API key (via X-API-Key header or api_key argument).

search_fonts

Searches the font catalog.

{
  "method": "tools/call",
  "params": {
    "name": "search_fonts",
    "arguments": {
      "query": "Roboto",
      "category": "sans-serif",
      "limit": 5
    }
  }
}

Note: api_key only required if no X-API-Key header was configured.

get_font_css

Generates @font-face CSS code. With local_paths: true, local file paths are used instead of CDN URLs.

# CDN-URLs (default)
{
  "method": "tools/call",
  "params": {
    "name": "get_font_css",
    "arguments": {
      "family": "Open Sans",
      "weights": "400,700",
      "styles": "normal,italic"
    }
  }
}

# Local file paths (for fully local hosting){
  "method": "tools/call",
  "params": {
    "name": "get_font_css",
    "arguments": {
      "family": "Open Sans",
      "weights": "400,700",
      "local_paths": true
    }
  }
}

download_font

Returns download URLs for all font files. For fully local font hosting.

{
  "method": "tools/call",
  "params": {
    "name": "download_font",
    "arguments": {
      "family": "Roboto",
      "weights": "400,700"
    }
  }
}

install_font NEW

All-in-one tool for local font hosting. Returns download commands and ready @font-face CSS in a single call.

{
  "method": "tools/call",
  "params": {
    "name": "install_font",
    "arguments": {
      "family": "Inter",
      "weights": "400,600,700",
      "fonts_dir": "assets/fonts",
      "css_path": "assets/css"
    }
  }
}

Parameters:

Response contains:

• mkdir + curl commands for copy-paste
• Ready @font-face CSS with correct relative paths
• HTML embedding instructions

get_font_link

Returns a ready HTML <link> tag (CDN variant).

{
  "method": "tools/call",
  "params": {
    "name": "get_font_link",
    "arguments": {
      "family": "Roboto",
      "weights": "400,700"
    }
  }
}

list_popular_fonts

Lists the most popular Google Fonts.

{
  "method": "tools/call",
  "params": {
    "name": "list_popular_fonts",
    "arguments": {
      "limit": 10
    }
  }
}

End session

DELETE https://fonts.realmaker.de/mcp
Mcp-Session-Id: abc123...

Rate Limits

Rate limit headers on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709000400

When exceeded: HTTP 429 with Retry-After header.

MCP requests also count against the rate limit of the used API key.

Error Handling

{
  "error": true,
  "message": "Error description",
  "status": 400
}

Practical Examples

AI Agent: Create website with fonts

# 1. Generate API keycurl -X POST https://fonts.realmaker.de/v1/register \
  -H "Content-Type: application/json" \
  -d '{}'

# 2. Search for fontscurl -H "X-API-Key: rf_..." \
  "https://fonts.realmaker.de/v1/fonts?search=sans&category=sans-serif&per_page=5"

# 3. Embed CSS in HTML# <link rel="stylesheet"
#   href="https://deinedomain.de/v1/css?family=Roboto&weights=400,700&api_key=rf_...">

Claude Code: MCP Workflow

# 1. Connect MCP server (once, with API key)claude mcp add-json rm-localfonts '{"type":"http","url":"https://fonts.realmaker.de/mcp","headers":{"X-API-Key":"rf_DEIN_KEY"}}'

# 2. Simply ask in chat:
"Download Google Font 'Inter' in 400 and 700 locally."

# Claude automatically uses install_font:
# → A single tool call# → Returns curl commands for downloading# → Returns ready @font-face CSS# → Claude executes everything and embeds it

PHP: Self-host font files

// Download font file and save locally$ch = curl_init('https://fonts.realmaker.de/v1/font/roboto/400-normal.woff2');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: rf_...']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$fontData = curl_exec($ch);
file_put_contents('fonts/roboto-400.woff2', $fontData);