Repository avatar
AI Tools
v0.2.8
active

qr-branding

io.github.quartzondev/qr-branding

Generate branded, scan-validated QR codes (manual, AI, templates, Wi-Fi, vCard, geo).

Documentation

QR Branding MCP server

MCP server for the QR Branding API. Lets Claude Desktop, Claude Code, Cursor, Cline, VS Code, ChatGPT desktop, and any other Model Context Protocol client generate branded QR codes, render any of the 118 curated templates, print-ready posters, or assemble Wi‑Fi / vCard / geo payloads — and check a design the way a phone camera will read it.

Every render is decoded server-side (ISO/IEC 18004) before it is returned, so a design that would not scan is caught here instead of on the printed piece.

Install

npx -y @qr-branding/mcp-server

The server starts without an API key: tools/list works, and any tool that needs the gateway explains how to get a key instead of failing silently. Read Limits and billing for what a key unlocks.

Get an API key

Sign in at qr-branding.com and create a key under Dashboard → API keys (/dashboard/keys). Keys look like qrb_xxx.... API access requires an active Studio pack; without one every call returns HTTP 402 studio_required.

Client config

Claude Desktop (claude_desktop_config.json) / Claude Code (.mcp.json)

Claude Desktop: Settings → Developer → Edit Config opens the file (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_xxx"
      }
    }
  }
}

Omit the env block to start in keyless mode.

Cursor / Cline / VS Code

Same command + args + env shape as above, in the client's own MCP settings file (%USERPROFILE%\.cursor\mcp.json, Cline's MCP Servers → Configure, .vscode/mcp.json).

Optional environment

  • QR_BRANDING_API_KEY — Studio key. Without it the tools that hit the gateway return a message explaining how to create one.
  • QR_BRANDING_API_BASE_URL — override the gateway URL. Default https://qr-branding.com. Useful for self-hosters and staging.

Remote server (no install)

The same eleven tools are served over Streamable HTTP at https://qr-branding.com/mcp.

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

Without a key the remote server answers in a keyless trial mode: every tool except qr_generate_ai, PNG up to 720 px, 20 tool calls per day per network. A Studio key unlocks SVG/PDF, up to 4K, posters and AI designs.

Clients that prefer a browser consent flow over pasting a key can use the bundled OAuth 2.1 server (dynamic client registration + PKCE): the 401 on https://qr-branding.com/mcp carries WWW-Authenticate: Bearer resource_metadata="https://qr-branding.com/.well-known/oauth-protected-resource", so the client discovers the authorization server and walks the user through consent.

Tools

ToolWhat it does
qr_generateManual QR generation with explicit colors, module/finder shapes, logo, caption, format.
qr_generate_aiPrompt-driven design — the server-side LLM picks the style for you.
qr_scan_checkRenders a design and decodes it under 13 simulated conditions (small print, distance, blur, dim light, low contrast, glare, noise, rotation), returning a grade, the smallest module in px, minimum print sizes and design warnings. No image is returned.
qr_list_templatesList the 118 curated templates (id, name, description, preview thumbnail URL).
qr_get_templateRead one template's full design config, to start from it and tweak with qr_generate.
qr_generate_from_templateRender a template by id with per-call overrides (content, colors, format/size).
qr_posterPrint-ready poster (A4/A5/A6/Letter, minimal/band/card/tent layouts, headline, bleed and crop marks) as vector PDF or PNG.
qr_build_wifiEncode Wi‑Fi credentials into a scannable Wi‑Fi QR.
qr_build_vcardEncode a contact card (vCard) into a QR.
qr_build_geoEncode latitude/longitude into a geo: URI QR.
qr_list_ai_providersThe LLM providers a bring-your-own-key AI design can target, with their default model.

For raster/SVG outputs the tool returns an inline image block so the assistant shows the QR directly in chat. For PDF the tool saves to a temp file and returns the path.

Usage examples

Ask your assistant things like:

  • "Generate a QR code for https://qr-branding.com with a circular module shape and gold color."
  • "Make me a luxury QR for my coffee brand — content is https://baristabros.example, gold dots on cream background."
  • "Is this design going to scan if I print it at 30 mm? Run the print check."
  • "List the QR templates in the 'business' category and render template 12 for https://acme.example."
  • "Encode my home Wi-Fi as a QR: SSID 'HomeNetwork', password 'wifi-please-7', WPA, hidden."
  • "Build a vCard QR for Jane Doe at Acme Inc., +1-555-867-5309, jane@acme.example, https://acme.example."
  • "Make a geo QR for 40.4168, -3.7038 (Madrid)."
  • "Give me an A4 poster with headline 'Scan for the menu' for https://acme.example/menu."

Limits and billing

API access is metered by API credits issued with your plan or topped up via promo codes. The free tier has no API quota — the gateway returns HTTP 402 out_of_api_credits and the tool surfaces that verbatim with an upgrade hint. Manage your plan at qr-branding.com/dashboard.

Privacy

This server only forwards your prompts/inputs to qr-branding.com. It does not phone home, does not include analytics or third-party telemetry, and reads QR_BRANDING_API_KEY only once at startup. The QR Branding privacy policy lives at qr-branding.com/privacy.

Develop locally

npm install
npm run build      # tsc → dist/
npm test           # tool surface + version parity

# smoke test the gateway with your key
QR_BRANDING_API_KEY=qrb_xxx npm run smoke
# include a sample QR generation
QR_BRANDING_API_KEY=qrb_xxx SMOKE_GENERATE=1 npm run smoke

# wire dist/index.js into your MCP client as a `command` for local testing

License

MIT — see LICENSE.

NPM
@qr-branding/mcp-server
Install Command
npm install @qr-branding/mcp-server
Runtime: npx

Remote