API Dokumentation

Authentifizierung

Alle API-Endpoints (außer Registrierung) erfordern einen API-Key. Drei Methoden werden unterstützt:

# Option 1: X-API-Key Header (empfohlen)
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

Erstellt einen neuen Account und gibt den API-Key zurück. E-Mail und Passwort sind optional – ohne sie wird ein anonymer API-Key generiert.

Request

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

// Minimal (anonymer API-Key):
{ }

// Mit E-Mail (Key-Recovery möglich):
{
  "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

Durchsucht den Font-Katalog mit optionalen Filtern.

Parameter

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

Generiert @font-face CSS-Code. Wichtigster Endpoint für die Integration.

Parameter

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-Einbindung

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

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

Liefert die eigentliche Font-Datei (Binary). Wird normalerweise automatisch vom CSS referenziert.

URL-Format

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

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

Response: Binary Font-Datei mit Cache-Control: public, max-age=31536000, immutable

GET /v1/account

Zeigt Account-Informationen und aktuellen Verbrauch.

{
  "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

Verbindung herstellen

Führe diesen Befehl einmalig im Terminal aus. Empfohlen: API-Key als Header – dann muss er nicht bei jedem Tool-Call angegeben werden:

# Empfohlen: API-Key als Header (einmalig konfigurieren)claude mcp add-json rm-localfonts '{"type":"http","url":"https://fonts.realmaker.de/mcp","headers":{"X-API-Key":"rf_DEIN_KEY"}}'

# Alternative: Ohne Header (API-Key pro Tool-Call)claude mcp add-json rm-localfonts '{"type":"http","url":"https://fonts.realmaker.de/mcp"}'

Danach kann Claude automatisch auf die LocalFonts-Tools zugreifen.

Tools anzeigen

Nach dem Setup kannst du die verfügbaren Tools im Browser prüfen:

# Tools-Info abrufen (GET-Endpoint)curl https://fonts.realmaker.de/mcp

Voraussetzungen

• Ein LocalFonts API-Key (kostenlos auf der Startseite registrieren)
• Claude Code CLI installiert
• API-Key via X-API-Key Header (empfohlen) oder als Tool-Argument

MCP Protokoll

realmaker LocalFonts implementiert das MCP HTTP Transport Protocol (JSON-RPC 2.0).

Endpoint

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

Session-Management

Der Server gibt bei initialize einen Mcp-Session-Id Header zurück. Dieser muss bei allen folgenden Requests mitgesendet werden.

Unterstützte Methoden

Beispiel: 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

Alle Tools erfordern einen gültigen API-Key (via X-API-Key Header oder api_key Argument).

search_fonts

Durchsucht den Font-Katalog.

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

Hinweis: api_key nur nötig, wenn kein X-API-Key Header konfiguriert wurde.

get_font_css

Generiert @font-face CSS-Code. Mit local_paths: true werden lokale Dateipfade statt CDN-URLs verwendet.

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

# Lokale Dateipfade (für vollständig lokales Hosting){
  "method": "tools/call",
  "params": {
    "name": "get_font_css",
    "arguments": {
      "family": "Open Sans",
      "weights": "400,700",
      "local_paths": true
    }
  }
}

download_font

Gibt Download-URLs für alle Font-Dateien zurück. Für komplett lokales Font-Hosting.

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

install_font NEU

All-in-one Tool für lokales Font-Hosting. Liefert Download-Commands und fertiges @font-face CSS in einem einzigen Call.

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

Parameter:

Response enthält:

• mkdir + curl Commands zum Copy-Paste
• Fertiges @font-face CSS mit korrekten relativen Pfaden
• HTML-Einbindungs-Anweisung

get_font_link

Gibt einen fertigen HTML <link>-Tag zurück (CDN-Variante).

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

list_popular_fonts

Listet die beliebtesten Google Fonts auf.

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

Session beenden

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

Rate Limits

Rate-Limit-Header auf jeder Response:

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

Bei Überschreitung: HTTP 429 mit Retry-After Header.

MCP-Requests zählen ebenfalls gegen das Rate-Limit des verwendeten API-Keys.

Fehlerbehandlung

{
  "error": true,
  "message": "Beschreibung des Fehlers",
  "status": 400
}

Praxisbeispiele

KI-Agent: Website mit Fonts erstellen

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

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

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

Claude Code: MCP-Workflow

# 1. MCP-Server verbinden (einmalig, mit API-Key)claude mcp add-json rm-localfonts '{"type":"http","url":"https://fonts.realmaker.de/mcp","headers":{"X-API-Key":"rf_DEIN_KEY"}}'

# 2. Im Chat einfach fragen:
"Lade die Google Font 'Inter' in 400 und 700 lokal herunter."

# Claude nutzt automatisch install_font:
# → Ein einziger Tool-Call# → Liefert curl-Commands zum Herunterladen# → Liefert fertiges @font-face CSS# → Claude führt alles aus und bindet es ein

PHP: Font-Dateien selbst hosten

// Font-Datei herunterladen und lokal speichern$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);