Aller au contenu

Serveur MCP de QR Branding

Parlez à votre éditeur ou à votre application de bureau IA et demandez-lui de générer des QR codes via le moteur de QR Branding. Le serveur MCP encapsule l'API publique sous la forme d'un ensemble d'outils que tout client compatible MCP peut appeler. Vous pouvez l'utiliser de deux façons :

  • Serveur distant sur https://qr-branding.com/mcp : rien à installer, il suffit de coller une URL et votre clé API dans le client.
  • Serveur local, le paquet npm @qr-branding/mcp-server (Node 20+), que votre client lance via stdio.

Les deux exposent les mêmes onze outils et s'authentifient avec la même clé API QR Branding. npm: @qr-branding/mcp-server.

Ce que vous obtenez

Onze outils associés à la passerelle publique sous https://qr-branding.com/api/v1/* :

OutilCe qu'il fait
qr_generateGénération manuelle : passez le sous-ensemble pratique de QrConfig (contenu, couleurs, formes des modules et des marqueurs, niveau d'ECC, format et taille de sortie, logo et légende facultatifs). Renvoie le PNG/JPG/WEBP/SVG/PDF rendu.
qr_scan_checkContrôle avant impression : effectue le rendu du design et le décode dans 13 conditions simulées (petits caractères, distance, flou, faible lumière, faible contraste, reflets, bruit, rotation). Renvoie la note, symbolModules, la version, smallestModulePx, le rapport par condition, la taille minimale d'impression à distance de table, de mur et de rue en mm, designScore et designWarnings. Fonctionne aussi dans l'essai sans clé.
qr_generate_aiPrompt IA côté serveur → QR. Donnez un prompt comme « coucher de soleil à l'aquarelle » avec une URL ou un texte de contenu ; le moteur choisit les couleurs et les formes, puis effectue le rendu.
qr_get_templateRécupère la configuration de design complète d'un modèle, pour l'inspecter puis l'ajuster avec qr_generate.
qr_posterAffiche prête à imprimer autour d'un design : a4/a5/a6/letter, mises en page minimal/band/card/tent, titre, consigne et pied de page, showLogo, fond perdu de 3 mm, traits de coupe et couleur d'accent. Renvoie un PDF vectoriel (par défaut) ou un PNG de 36 à 300 dpi.
qr_list_templatesParcourez les 118 modèles prédéfinis (id, nom, description, URL de la miniature d'aperçu).
qr_generate_from_templateRend un modèle par id avec des ajustements à chaque appel : changez le contenu, remplacez les couleurs, adaptez le format de sortie.
qr_build_wifiEncode des identifiants Wi-Fi (WIFI:T:WPA;S:...;P:...;;) et renvoie la chaîne ainsi que le QR.
qr_build_vcardEncode une carte de contact (vCard) et renvoie la chaîne ainsi que le QR.
qr_build_geoEncode un URI geo: à partir de la latitude et de la longitude et renvoie la chaîne ainsi que le QR.
qr_list_ai_providersListe les fournisseurs de LLM que le moteur accepte pour les designs IA avec votre propre clé (POST /api/qr/ai/generate) : l'id de chaque fournisseur, son modèle par défaut et les ids de modèle recommandés. Tout id de modèle proposé par votre fournisseur fonctionne ; la liste est une recommandation, pas une liste d'autorisation. qr_generate_ai n'en a pas besoin, car il passe par le chemin géré.

qr_build_vcard prend en charge ces champs : firstName (obligatoire), lastName, organization, phone, email et url. L'adresse postale, le poste et les notes ne sont pas encore pris en charge. qr_build_geo accepte uniquement latitude et longitude (pas d'altitude).

Les formats bitmap (PNG, JPG, WEBP) et le SVG reviennent sous forme de blocs de contenu image en ligne : les clients qui affichent les images MCP montrent donc le QR directement dans la conversation. Les PDF ne peuvent pas être intégrés en ligne : le serveur local les écrit dans un fichier temporaire et renvoie le chemin ; le serveur distant les renvoie comme ressource application/pdf intégrée.

Prérequis

  1. Une clé API : connectez-vous sur qr-branding.com, allez dans Tableau de bord → Clés API, cliquez sur Générer la clé et copiez la valeur qrb_… immédiatement. Vous ne la reverrez plus, mais vous pouvez en émettre d'autres.
  2. Formule Studio : l'API exige un pack Studio actif. Avec toute autre formule, les appels d'outils échouent avec studio_required, et l'erreur parvient au modèle avec une suggestion de passer à Studio. Les générations IA consomment en plus des crédits IA Studio (out_of_api_credits une fois épuisés).
  3. Node 20+, uniquement pour le serveur local, sur la machine qui héberge le processus MCP (en général votre ordinateur portable). npx se charge de l'installation.

Serveur distant (Streamable HTTP)

Le endpoint est https://qr-branding.com/mcp, qui utilise le transport Streamable HTTP de MCP (sans état, réponses JSON). Envoyez votre clé dans l'un ou l'autre de ces en-têtes :

  • Authorization: Bearer qrb_PASTE_YOUR_KEY (ce que la plupart des clients configurent)
  • X-API-Key: qrb_PASTE_YOUR_KEY (le même en-tête que l'API REST)

Une requête avec une clé invalide ou révoquée reçoit 401 avec un en-tête WWW-Authenticate: Bearer.

Essai sans clé. Sans aucune clé, le serveur distant fonctionne en mode essai : tous les outils sauf qr_generate_ai, des rendus PNG de 720 px maximum et 20 appels d'outils par jour et par réseau. Ajoutez une clé pour débloquer les designs IA, tous les formats et tailles, et les limites de votre offre. Le serveur npm local exige toujours une clé.

Claude Code (CLI)

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

Lancez /mcp dans une session pour vérifier que le serveur est connecté, puis demandez par exemple « génère un QR pour https://qr-branding.com avec des modules en forme de feuille et une couleur or » ; Claude appellera qr_generate.

Cursor

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

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

VS Code (mode agent de GitHub Copilot)

.vscode/mcp.json dans votre espace de travail :

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

Autres clients

Tout client qui prend en charge Streamable HTTP avec des en-têtes personnalisés fonctionne avec la même paire url + headers. Un client qui ne lance que des serveurs stdio peut utiliser le serveur local.

Connecteurs personnalisés de claude.ai et de Claude Desktop

Les connecteurs personnalisés ajoutés depuis claude.ai (le web, ainsi que les réglages Connecteurs de Claude Desktop) s'authentifient avec OAuth, que le serveur distant prend en charge : indiquez https://qr-branding.com/mcp au connecteur et le client déroule le flux OAuth 2.1 de lui-même. Les clients capables d'envoyer un en-tête avec la clé API fonctionnent toujours ainsi, et Claude Desktop peut aussi utiliser le serveur local en stdio avec QR_BRANDING_API_KEY (ci-dessous).

Serveur local (npm, stdio)

Votre client lance npx @qr-branding/mcp-server et échange du JSON-RPC sur l'entrée et la sortie standard du processus. La clé se place dans la variable d'environnement 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)

Ouvrez le fichier de configuration :

  • 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" }
    }
  }
}

Quittez complètement Claude Desktop puis rouvrez-le. Le serveur QR Branding doit apparaître comme disponible dans le menu des outils, à côté du champ de saisie.

Cursor

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

Redémarrez Cursor. Les outils sont exposés à la fois à l'agent du chat et à Composer.

ChatGPT Desktop

ChatGPT Desktop lit ~/.openai/chatgpt/mcp-config.json (le chemin peut varier selon la version : vérifiez dans 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 (extension VS Code / JetBrains)

Dans votre configuration Continue (~/.continue/config.json ou .continue/config.json de l'espace de travail), sous mcpServers :

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

Zed

Ouvrez ~/.config/zed/settings.json et ajoutez sous 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" }
  }
}

Variables d'environnement (serveur local)

VariableValeur par défautPourquoi la modifier
QR_BRANDING_API_KEY(non définie)Votre clé qrb_…. Depuis la 0.2.1, le serveur démarre sans elle et écrit un avertissement : tools/list fonctionne toujours, et les appels qui nécessitent l'API renvoient une erreur missing_api_key. L'essai sans clé n'existe que sur le serveur distant.
QR_BRANDING_API_BASE_URLhttps://qr-branding.comPointer vers le staging ou une passerelle auto-hébergée. Utile en développement.

Vérifier que tout fonctionne

Serveur distant : listez les outils avec curl :

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"}'

Serveur local : lancez le smoke test depuis le code source :

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

Le smoke test interroge /api/v1/qr/ping et /api/v1/qr/templates, affiche le nombre de modèles et (avec SMOKE_GENERATE=1) génère de bout en bout un tout petit QR de test.

Coûts et limites

  • Les appels de génération : la génération manuelle, les modèles et les utilitaires de contenu ne consomment pas de crédits ; la génération IA sur nos clés (qr_generate_ai) consomme un crédit IA Studio. Les appels de liste et de métadonnées de modèles n'en consomment pas non plus. Voir Tarifs et crédits.
  • Les limites de débit sont celles de la passerelle : voir la vue d'ensemble de l'API. Sur le serveur distant, chaque appel d'outil compte comme une requête dans la limite par minute et le plafond quotidien de votre clé ; le handshake et tools/list ne comptent que dans la limite par réseau.
  • Le coût côté assistant IA dépend de la tarification de votre assistant (usage de Claude, abonnement ChatGPT, etc.). Le serveur MCP lui-même est gratuit.

Confidentialité et sécurité

  • Le serveur MCP transmet à qr-branding.com vos prompts ainsi que les URL ou textes que vous lui passez. Aucune télémétrie tierce, aucun SDK d'analytique.
  • La clé API reste dans la configuration de votre client ; elle n'apparaît jamais dans les transcriptions de conversation ni dans le contexte du modèle. Le serveur distant ne la reçoit qu'en HTTPS et la compare à un hash, comme l'API REST.
  • Faites tourner la clé quand vous voulez dans Tableau de bord → Clés API ; les anciennes clés sont révoquées instantanément.

Dépannage

  • « QR_BRANDING_API_KEY not set » (local) : la variable d'environnement n'a pas atteint le processus npx lancé. Vérifiez que le JSON est valide et redémarrez l'application hôte.
  • 401 invalid_api_key / missing_api_key (distant) : l'en-tête n'est pas arrivé ou la clé a été révoquée. Vérifiez l'en-tête Authorization: Bearer qrb_… dans la configuration du client.
  • studio_required : votre compte n'a pas de pack Studio actif (Starter et Pro n'incluent que l'éditeur). Passez à Studio sur la page tarifs.
  • out_of_api_credits : vos crédits IA Studio sont épuisés. Rechargez sur la page tarifs.
  • L'image ne s'affiche pas en ligne : votre client ne gère peut-être pas le contenu image MCP. Les bitmaps et les SVG utilisent le type de contenu image de la spécification ; les PDF reviennent sous forme de chemin de fichier (local) ou de ressource intégrée (distant).
  • Erreurs réseau / délais d'attente : la passerelle se trouve sur https://qr-branding.com. Si votre réseau la bloque, remplacez QR_BRANDING_API_BASE_URL (serveur local).

Et ensuite

Nous suivons ces points pour les prochaines versions :

  • Un outil qr_dynamic_create qui crée des QR dynamiques imprimables (le redirecteur q.qr-branding.com/{slug}) sans quitter la conversation.
  • Des gestionnaires de ressources pour parcourir les modèles comme ressources MCP (afin que les clients dotés d'un sélecteur de ressources puissent les afficher dans leur interface).

Questions ou demandes de fonctionnalités : écrivez à support@qr-branding.com.