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 sept outils et s'authentifient avec la même clé API QR Branding. Code source : mcp-server/.

Ce que vous obtenez

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

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 sans clé valide reçoit 401 avec un en-tête WWW-Authenticate: Bearer.

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 MCP de QR Branding ne prend pas encore en charge : ils ne peuvent pas envoyer d'en-tête avec la clé API. D'ici là, utilisez le serveur local dans Claude Desktop (ci-dessous) ou Claude Code avec le serveur distant.

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)

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 :

• OAuth sur le serveur distant, afin de pouvoir l'ajouter comme connecteur personnalisé dans claude.ai et dans les autres clients qui l'exigent.
• Un outil qr_dynamic_create qui crée des QR dynamiques imprimables (le redirecteur /q/{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).

Ouvrez des tickets ou des demandes de fonctionnalités sur le dépôt. Le code du paquet se trouve dans le même monorepo que le moteur.