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 sieben Tools und authentifizieren sich mit demselben QR-Branding-API-Schlüssel. Quellcode: mcp-server/.

Was du bekommst

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

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 ohne gültigen Schlüssel erhält 401 mit einem WWW-Authenticate: Bearer-Header.

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 QR-Branding-MCP-Server noch nicht unterstützt: Sie können keinen Header mit dem API-Schlüssel senden. Bis dahin nutze den lokalen Server in Claude Desktop (unten) oder Claude Code mit dem Remote-Server.

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)

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:

• OAuth auf dem Remote-Server, damit er in claude.ai und anderen Clients, die es verlangen, als benutzerdefinierter Connector hinzugefügt werden kann.
• Ein Tool qr_dynamic_create, das druckbare dynamische QRs (den Redirector /q/{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).

Eröffne Issues oder Feature-Wünsche im Repository. Der Paketcode liegt im selben Monorepo wie die Engine.