QR Branding

具品牌風格的 QR code,含標誌、形狀和外框,列印前會在伺服器端解碼驗證。8 種工具:設計、118 種範本、AI 提示詞設計、Wi-Fi/vCard/地理位置,以及列印掃描檢查。遠端端點,無需金鑰即可免費試用。

託管 MCP 伺服器

npx add-mcp 'https://qr-branding.com/mcp'

可安裝到 Claude Code、Codex、Cursor 等客戶端

文件

QR Branding MCP server

Talk to your editor or AI desktop app and have it generate QR codes through the QR Branding engine. The MCP server wraps the public API as a set of tools any MCP-compatible client can call. You can use it two ways:

  • Remote server at https://qr-branding.com/mcp: nothing to install, you paste a URL and your API key into the client.
  • Local server, the npm package @qr-branding/mcp-server (Node 20+), which your client launches over stdio.

Both expose the same eleven tools and are authenticated with the same QR Branding API key. npm: @qr-branding/mcp-server.

What you get

Eleven tools mapped to the public gateway under https://qr-branding.com/api/v1/*:

ToolWhat it does
qr_generateManual generation: pass the practical subset of QrConfig (content, colors, module/finder shapes, ECC level, output format/size, optional logo and caption). Returns the rendered PNG/JPG/WEBP/SVG/PDF.
qr_scan_checkPrint check: renders the design and decodes it under 13 simulated conditions (small print, distance, blur, dim light, low contrast, glare, noise, rotation). Returns the grade, symbolModules, version, smallestModulePx, the per-condition report, the minimum print size at table/wall/street distance in mm, designScore and designWarnings. Runs in the keyless trial too.
qr_generate_aiServer-side AI prompt → QR. Give a prompt like "watercolor sunset" plus a content URL/text; the engine picks colors/shapes and renders.
qr_get_templateFetch a curated template's full design config, so an agent can inspect it and then tweak it with qr_generate.
qr_posterPrint-ready poster around one design: a4 / a5 / a6 / letter, layouts minimal / band / card / tent, headline, instruction and footer text, showLogo, 3 mm bleed, crop marks and an accent color. Returns a vector PDF (default) or a PNG at 36–300 dpi.
qr_list_templatesBrowse the 118 pre-designed templates (id, name, description, preview thumbnail URL).
qr_generate_from_templateRender a template by id with per-call overrides: change the content, swap colors, adjust output format.
qr_build_wifiEncode Wi-Fi credentials (WIFI:T:WPA;S:...;P:...;;) and return both the string and the QR.
qr_build_vcardEncode a contact card (vCard) and return string + QR.
qr_build_geoEncode a geo: URI from latitude and longitude and return string + QR.
qr_list_ai_providersLists the LLM providers the engine accepts for bring-your-own-key AI designs (POST /api/qr/ai/generate): each provider id, its default model and the recommended model ids. Any model id your provider offers works; the list is a recommendation, not an allowlist. qr_generate_ai does not need it because it uses the managed path.

qr_build_vcard supports these fields: firstName (required), lastName, organization, phone, email and url. Postal address, job title and notes are not supported yet. qr_build_geo takes latitude and longitude only (no altitude).

Bitmap formats (PNG, JPG, WEBP) and SVG come back as inline image content blocks, so clients that render MCP images show the QR straight in the chat. PDFs can't be inlined: the local server writes them to a temp file and returns the path; the remote server returns them as an embedded application/pdf resource.

Prerequisites

  1. An API key: sign in at qr-branding.com, go to Dashboard → API keys, click Generate key, copy the qrb_… value once. You won't see it again, but you can issue more.
  2. Studio plan: the API requires an active Studio pack. On any other plan tool calls fail with studio_required, and the error reaches the model with an upgrade hint. AI generations also spend Studio AI credits (out_of_api_credits once they run out).
  3. Node 20+, only for the local server, on the machine that hosts the MCP process (your laptop, normally). npx handles the install.

Remote server (Streamable HTTP)

The endpoint is https://qr-branding.com/mcp, speaking MCP's Streamable HTTP transport (stateless, JSON responses). Send your key in either header:

  • Authorization: Bearer qrb_PASTE_YOUR_KEY (what most clients configure)
  • X-API-Key: qrb_PASTE_YOUR_KEY (the same header as the REST API)

A request with an invalid or revoked key gets 401 with a WWW-Authenticate: Bearer header.

Keyless trial. Without any key the remote server still works in trial mode: every tool except qr_generate_ai runs, renders are PNG at most 720 px, and each network gets 20 tool calls per day. Add a key to unlock AI designs, every format and size, and your plan's limits. The local npm server always needs a key.

Claude Code (CLI)

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

Run /mcp in a session to check the server is connected, then ask things like "generate a QR for https://qr-branding.com with a leaf module shape and gold color" and Claude will call qr_generate.

Cursor

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

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

VS Code (GitHub Copilot agent mode)

.vscode/mcp.json in your workspace:

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

Other clients

Any client that supports Streamable HTTP with custom headers works with the same url + headers pair. A client that only launches stdio servers can use the local server instead.

claude.ai and Claude Desktop custom connectors

Custom connectors added from claude.ai (web, and the Connectors settings of Claude Desktop) authenticate with OAuth, which the remote server supports: point the connector at https://qr-branding.com/mcp and the client runs the OAuth 2.1 flow on its own. Clients that can send an API key header keep working that way, and Claude Desktop can also run the local stdio server with QR_BRANDING_API_KEY (below).

Local server (npm, stdio)

Your client launches npx @qr-branding/mcp-server and talks JSON-RPC over the process's stdin/stdout. The key goes in the QR_BRANDING_API_KEY environment variable.

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)

Open the config 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_PASTE_YOUR_KEY" }
    }
  }
}

Fully quit and reopen Claude Desktop. The QR Branding server should appear as available in the tools menu next to the message input.

Cursor

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

Restart Cursor. The tools are exposed to both the in-chat agent and the Composer.

ChatGPT Desktop

ChatGPT Desktop reads ~/.openai/chatgpt/mcp-config.json (path may vary by version; check 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 extension)

In your Continue config (~/.continue/config.json or workspace .continue/config.json), under mcpServers:

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

Zed

Open ~/.config/zed/settings.json and add under 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" }
  }
}

Environment variables (local server)

VariableDefaultWhy you might change it
QR_BRANDING_API_KEY(unset)Your qrb_… key. Since 0.2.1 the server starts without it and writes one warning: tools/list still works, and tool calls that need the API return a missing_api_key error. The keyless trial exists only on the remote endpoint.
QR_BRANDING_API_BASE_URLhttps://qr-branding.comPoint at staging or a self-hosted gateway. Useful for development.

Verifying it works

Remote server: list the tools with 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"}'

Local server: run the smoke test from the source checkout:

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

The smoke test probes /api/v1/qr/ping and /api/v1/qr/templates, prints the template count, and (with SMOKE_GENERATE=1) generates a tiny test QR end-to-end.

Costs and limits

  • Generation calls: manual generation, templates and content helpers spend no credits; AI generation on our keys (qr_generate_ai) spends one Studio AI credit. List and template-metadata calls don't consume credits either. See Pricing & credits.
  • Rate limits are the gateway's: see the API overview. On the remote server every tool call counts as one request against your key's per-minute limit and daily cap; the handshake and tools/list only count against the per-network limit.
  • Cost on the AI assistant side depends on your assistant's pricing (Claude usage, ChatGPT subscription, etc). The MCP server itself is free.

Privacy and security

  • The MCP server forwards your prompts and any URLs/text you pass through to qr-branding.com. No third-party telemetry, no analytics SDKs.
  • The API key lives in your client's configuration; it never appears in chat transcripts or model context. The remote server only receives it over HTTPS and checks it against a hash, like the REST API.
  • Rotate the key any time at Dashboard → API keys; old keys revoke instantly.

Troubleshooting

  • "QR_BRANDING_API_KEY not set" (local): the env didn't reach the spawned npx process. Double-check the JSON is valid and restart the host app.
  • 401 invalid_api_key / missing_api_key (remote): the header didn't arrive or the key was revoked. Check the Authorization: Bearer qrb_… header in the client config.
  • studio_required: your account has no active Studio pack (Starter/Pro are editor-only). Get Studio at pricing.
  • out_of_api_credits: your Studio AI credits are used up. Top up at pricing.
  • Image doesn't render inline: your client may not handle MCP image content. Bitmaps and SVGs use the spec's image content type; PDFs come back as a file path (local) or an embedded resource (remote).
  • Network errors / timeouts: the gateway lives at https://qr-branding.com. If your network blocks it, override QR_BRANDING_API_BASE_URL (local server).

What's next

We're tracking these for upcoming releases:

  • A qr_dynamic_create tool that mints printable dynamic QRs (the q.qr-branding.com/{slug} redirector) without leaving the chat.
  • Resource handlers for browsing the templates as MCP resources (so clients with resource pickers can show them in their UI).

Questions or feature requests: write to support@qr-branding.com.