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 seven tools and are authenticated with the same QR Branding API key. Source: mcp-server/.

What you get

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

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 without a valid key gets 401 with a 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"

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 QR Branding MCP server does not support yet: they can't send an API key header. Until it does, use the local server in Claude Desktop (below) or Claude Code with the remote server.

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)

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:

• OAuth on the remote server, so it can be added as a custom connector in claude.ai and other clients that require it.
• A qr_dynamic_create tool that mints printable dynamic QRs (the /q/{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).

Open issues or feature requests on the repo. The package source is in the same monorepo as the engine.