Zum Inhalt springen

QR Branding MCP-Server

Sprich mit deinem Editor oder deiner KI-Desktop-App und lass sie QR-Codes über die QR-Branding-Engine erzeugen. Der MCP-Server verpackt die öffentliche API als Satz von Tools, die jeder MCP-kompatible Client aufrufen kann. Du kannst ihn auf zwei Arten nutzen:

  • Remote-Server unter https://qr-branding.com/mcp: nichts zu installieren, du fügst nur eine URL und deinen API-Schlüssel in den Client ein.
  • Lokaler Server, das npm-Paket @qr-branding/mcp-server (Node 20+), das dein Client über stdio startet.

Beide bieten dieselben elf Tools und authentifizieren sich mit demselben QR-Branding-API-Schlüssel. npm: @qr-branding/mcp-server.

Was du bekommst

Elf Tools, die auf das öffentliche Gateway unter https://qr-branding.com/api/v1/* abgebildet sind:

ToolWas es macht
qr_generateManuelle Generierung: übergib die praktische Teilmenge von QrConfig (Inhalt, Farben, Modul- und Marker-Formen, ECC-Stufe, Ausgabeformat und -größe, optional Logo und Beschriftung). Liefert das gerenderte PNG/JPG/WEBP/SVG/PDF.
qr_scan_checkDruckprüfung: rendert das Design und dekodiert es unter 13 simulierten Bedingungen (Kleindruck, Entfernung, Unschärfe, schwaches Licht, geringer Kontrast, Blendung, Rauschen, Drehung). Liefert die Note, symbolModules, die Version, smallestModulePx, den Bericht je Bedingung, die Mindestdruckgröße auf Tisch-, Wand- und Straßenabstand in mm, designScore und designWarnings. Läuft auch im Test ohne Schlüssel.
qr_generate_aiKI-Prompt auf dem Server → QR. Gib einen Prompt wie „Aquarell-Sonnenuntergang“ plus eine Inhalts-URL oder einen Text an; die Engine wählt Farben und Formen und rendert.
qr_get_templateRuft die vollständige Designkonfiguration einer Vorlage ab, damit sie geprüft und anschließend mit qr_generate angepasst werden kann.
qr_posterDruckfertiges Poster um ein Design: a4/a5/a6/letter, Layouts minimal/band/card/tent, Überschrift, Hinweis und Fußzeile, showLogo, 3 mm Beschnitt, Schnittmarken und Akzentfarbe. Liefert ein Vektor-PDF (Standard) oder ein PNG mit 36–300 dpi.
qr_list_templatesDurchsuche die 118 vorgefertigten Vorlagen (ID, Name, Beschreibung, URL des Vorschaubilds).
qr_generate_from_templateRendert eine Vorlage per ID mit Anpassungen pro Aufruf: Inhalt ändern, Farben tauschen, Ausgabeformat anpassen.
qr_build_wifiKodiert WLAN-Zugangsdaten (WIFI:T:WPA;S:...;P:...;;) und liefert den String und den QR.
qr_build_vcardKodiert eine Kontaktkarte (vCard) und liefert String und QR.
qr_build_geoKodiert einen geo:-URI aus Breiten- und Längengrad und liefert String und QR.
qr_list_ai_providersListet die LLM-Anbieter auf, die die Engine für KI-Designs mit eigenem Schlüssel akzeptiert (POST /api/qr/ai/generate): die ID jedes Anbieters, sein Standardmodell und die empfohlenen Modell-IDs. Jede Modell-ID, die dein Anbieter anbietet, funktioniert; die Liste ist eine Empfehlung, keine Positivliste. qr_generate_ai braucht sie nicht, weil es den verwalteten Pfad nutzt.

qr_build_vcard unterstützt diese Felder: firstName (Pflicht), lastName, organization, phone, email und url. Postadresse, Position und Notizen werden noch nicht unterstützt. qr_build_geo nimmt nur latitude und longitude entgegen (keine Höhe).

Bitmap-Formate (PNG, JPG, WEBP) und SVG kommen als Inline-Bildinhalte zurück, sodass Clients, die MCP-Bilder darstellen, den QR direkt im Chat zeigen. PDFs lassen sich nicht inline einbetten: Der lokale Server schreibt sie in eine temporäre Datei und liefert den Pfad; der Remote-Server liefert sie als eingebettete Ressource vom Typ application/pdf.

Voraussetzungen

  1. Ein API-Schlüssel: Melde dich auf qr-branding.com an, geh zu Dashboard → API-Schlüssel, klick auf Schlüssel erzeugen und kopiere den Wert qrb_… sofort. Du siehst ihn nie wieder, kannst aber weitere ausstellen.
  2. Studio-Plan: Die API setzt ein aktives Studio-Paket voraus. Mit jedem anderen Plan schlagen Tool-Aufrufe mit studio_required fehl, und der Fehler erreicht das Modell mit einem Upgrade-Hinweis. KI-Generierungen verbrauchen zusätzlich Studio-KI-Credits (out_of_api_credits, sobald sie aufgebraucht sind).
  3. Node 20+, nur für den lokalen Server, auf dem Rechner, der den MCP-Prozess hostet (normalerweise dein Laptop). npx übernimmt die Installation.

Remote-Server (Streamable HTTP)

Der Endpunkt ist https://qr-branding.com/mcp und spricht den Streamable-HTTP-Transport von MCP (zustandslos, JSON-Antworten). Sende deinen Schlüssel in einem der beiden Header:

  • Authorization: Bearer qrb_PASTE_YOUR_KEY (was die meisten Clients konfigurieren)
  • X-API-Key: qrb_PASTE_YOUR_KEY (derselbe Header wie bei der REST-API)

Eine Anfrage mit ungültigem oder widerrufenem Schlüssel erhält 401 mit einem WWW-Authenticate: Bearer-Header.

Testmodus ohne Schlüssel. Ganz ohne Schlüssel läuft der Remote-Server im Testmodus: alle Tools außer qr_generate_ai, Renderings als PNG mit höchstens 720 px und 20 Tool-Aufrufe pro Tag und Netzwerk. Mit einem Schlüssel schaltest du KI-Designs, alle Formate und Größen sowie die Limits deines Plans frei. Der lokale npm-Server braucht immer einen Schlüssel.

Claude Code (CLI)

claude mcp add --transport http qr-branding https://qr-branding.com/mcp \
  --header "Authorization: Bearer qrb_PASTE_YOUR_KEY"

Führe /mcp in einer Sitzung aus, um zu prüfen, ob der Server verbunden ist, und frag zum Beispiel „Erzeuge einen QR für https://qr-branding.com mit Blatt-Modulform und Goldfarbe“; Claude ruft dann qr_generate auf.

Cursor

~/.cursor/mcp.json (oder Settings → MCP):

{
  "mcpServers": {
    "qr-branding": {
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

VS Code (GitHub-Copilot-Agentmodus)

.vscode/mcp.json in deinem Workspace:

{
  "servers": {
    "qr-branding": {
      "type": "http",
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

Andere Clients

Jeder Client, der Streamable HTTP mit benutzerdefinierten Headern unterstützt, funktioniert mit demselben Paar aus url + headers. Ein Client, der nur stdio-Server startet, kann stattdessen den lokalen Server nutzen.

Benutzerdefinierte Connectors in claude.ai und Claude Desktop

Benutzerdefinierte Connectors, die über claude.ai hinzugefügt werden (Web und die Connector-Einstellungen von Claude Desktop), authentifizieren sich per OAuth, das der Remote-Server unterstützt: Richte den Connector auf https://qr-branding.com/mcp, dann führt der Client den OAuth-2.1-Flow selbst durch. Clients, die einen Header mit dem API-Schlüssel senden können, funktionieren weiterhin so, und Claude Desktop kann auch den lokalen stdio-Server mit QR_BRANDING_API_KEY nutzen (unten).

Lokaler Server (npm, stdio)

Dein Client startet npx @qr-branding/mcp-server und spricht JSON-RPC über stdin/stdout des Prozesses. Der Schlüssel kommt in die Umgebungsvariable QR_BRANDING_API_KEY.

Claude Code (CLI)

claude mcp add qr-branding --env QR_BRANDING_API_KEY=qrb_PASTE_YOUR_KEY -- npx -y @qr-branding/mcp-server

Claude Desktop (macOS / Windows)

Öffne die Konfigurationsdatei:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Beende Claude Desktop vollständig und öffne es neu. Der QR-Branding-Server sollte im Tool-Menü neben dem Eingabefeld als verfügbar erscheinen.

Cursor

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Starte Cursor neu. Die Tools stehen sowohl dem Chat-Agenten als auch dem Composer zur Verfügung.

ChatGPT Desktop

ChatGPT Desktop liest ~/.openai/chatgpt/mcp-config.json (der Pfad kann je nach Version abweichen – prüf das unter Settings → Beta features → Model Context Protocol):

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Continue (VS-Code-/JetBrains-Erweiterung)

In deiner Continue-Konfiguration (~/.continue/config.json oder .continue/config.json im Workspace) unter mcpServers:

"mcpServers": [
  {
    "name": "qr-branding",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
]

Zed

Öffne ~/.config/zed/settings.json und ergänze unter context_servers:

"context_servers": {
  "qr-branding": {
    "source": "custom",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
}

Umgebungsvariablen (lokaler Server)

VariableStandardWarum du sie ändern könntest
QR_BRANDING_API_KEY(nicht gesetzt)Dein qrb_…-Schlüssel. Seit 0.2.1 startet der Server auch ohne ihn und schreibt eine Warnung: tools/list funktioniert weiterhin, und Tool-Aufrufe, die die API brauchen, liefern einen missing_api_key-Fehler. Den Test ohne Schlüssel gibt es nur auf dem Remote-Server.
QR_BRANDING_API_BASE_URLhttps://qr-branding.comAuf Staging oder ein selbst gehostetes Gateway zeigen. Praktisch für die Entwicklung.

Prüfen, ob es funktioniert

Remote-Server: Liste die Tools mit curl auf:

curl -s https://qr-branding.com/mcp \
  -H "Authorization: Bearer qrb_PASTE_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Lokaler Server: Führe den Smoke-Test aus dem Quellcode-Checkout aus:

cd mcp-server
npm install
QR_BRANDING_API_KEY=qrb_xxx npm run smoke
QR_BRANDING_API_KEY=qrb_xxx SMOKE_GENERATE=1 npm run smoke

Der Smoke-Test fragt /api/v1/qr/ping und /api/v1/qr/templates ab, gibt die Anzahl der Vorlagen aus und erzeugt (mit SMOKE_GENERATE=1) durchgängig einen winzigen Test-QR.

Kosten und Limits

  • Generierungsaufrufe: Manuelle Generierung, Vorlagen und Inhalts-Helfer verbrauchen keine Credits; eine KI-Generierung mit unseren Schlüsseln (qr_generate_ai) kostet einen Studio-KI-Credit. Aufrufe für Listen und Vorlagen-Metadaten verbrauchen ebenfalls keine Credits. Siehe Preise & Credits.
  • Rate-Limits sind die des Gateways: siehe die API-Übersicht. Beim Remote-Server zählt jeder Tool-Aufruf als eine Anfrage gegen das Minutenlimit und das Tageskontingent deines Schlüssels; Handshake und tools/list zählen nur gegen das Limit pro Netzwerk.
  • Kosten auf Seiten des KI-Assistenten hängen von der Preisgestaltung deines Assistenten ab (Claude-Nutzung, ChatGPT-Abo usw.). Der MCP-Server selbst ist kostenlos.

Datenschutz und Sicherheit

  • Der MCP-Server leitet deine Prompts und alle URLs oder Texte, die du übergibst, an qr-branding.com weiter. Keine Telemetrie von Drittanbietern, keine Analytics-SDKs.
  • Der API-Schlüssel liegt in der Konfiguration deines Clients; er taucht weder in Chat-Verläufen noch im Kontext des Modells auf. Der Remote-Server erhält ihn nur über HTTPS und prüft ihn gegen einen Hash, genau wie die REST-API.
  • Rotiere den Schlüssel jederzeit unter Dashboard → API-Schlüssel; alte Schlüssel werden sofort widerrufen.

Fehlerbehebung

  • „QR_BRANDING_API_KEY not set“ (lokal): Die Umgebungsvariable hat den gestarteten npx-Prozess nicht erreicht. Prüf, ob das JSON gültig ist, und starte die Host-App neu.
  • 401 invalid_api_key / missing_api_key (remote): Der Header ist nicht angekommen oder der Schlüssel wurde widerrufen. Prüf den Header Authorization: Bearer qrb_… in der Client-Konfiguration.
  • studio_required: Dein Konto hat kein aktives Studio-Paket (Starter/Pro sind nur für den Editor). Hol dir Studio unter Preise.
  • out_of_api_credits: Deine Studio-KI-Credits sind aufgebraucht. Lade unter Preise nach.
  • Bild wird nicht inline angezeigt: Dein Client verarbeitet MCP-Bildinhalte möglicherweise nicht. Bitmaps und SVGs nutzen den Bildinhaltstyp der Spezifikation; PDFs kommen als Dateipfad (lokal) oder als eingebettete Ressource (remote) zurück.
  • Netzwerkfehler / Timeouts: Das Gateway liegt unter https://qr-branding.com. Blockiert dein Netzwerk es, überschreibe QR_BRANDING_API_BASE_URL (lokaler Server).

Wie es weitergeht

Diese Punkte verfolgen wir für kommende Versionen:

  • Ein Tool qr_dynamic_create, das druckbare dynamische QRs (den Redirector q.qr-branding.com/{slug}) erzeugt, ohne den Chat zu verlassen.
  • Ressourcen-Handler, um die Vorlagen als MCP-Ressourcen zu durchsuchen (damit Clients mit Ressourcenauswahl sie in ihrer Oberfläche anzeigen können).

Fragen oder Feature-Wünsche: schreib an support@qr-branding.com.