QR Branding MCP 服务器

直接与编辑器或 AI 桌面应用对话，让它通过 QR Branding 引擎生成二维码。MCP 服务器把公开 API 封装为一组工具，任何兼容 MCP 的客户端都能调用。有两种使用方式：

远程服务器，地址为 https://qr-branding.com/mcp：无需安装，只需把 URL 和你的 API 密钥粘贴到客户端中。
本地服务器，即 npm 包 @qr-branding/mcp-server（Node 20+），由客户端通过 stdio 启动。

两者提供相同的七个工具，并使用同一个 QR Branding API 密钥认证。源码：mcp-server/。

你将获得什么

七个工具，对应 https://qr-branding.com/api/v1/* 下的公开网关：

工具	功能
`qr_generate`	手动生成：传入 `QrConfig` 的常用子集（内容、颜色、模块和定位点形状、ECC 级别、输出格式和尺寸，以及可选的徽标和说明文字）。返回渲染好的 PNG/JPG/WEBP/SVG/PDF。
`qr_generate_ai`	服务端 AI 提示词 → 二维码。给出类似“水彩日落”的提示词，再加上内容 URL 或文本；引擎会选择颜色和形状并完成渲染。
`qr_list_templates`	浏览 118 个预设计模板（ID、名称、描述、预览缩略图 URL）。
`qr_generate_from_template`	按 ID 渲染模板，并支持每次调用单独覆盖：修改内容、替换颜色、调整输出格式。
`qr_build_wifi`	编码 Wi-Fi 凭据（`WIFI:T:WPA;S:...;P:...;;`），同时返回字符串和二维码。
`qr_build_vcard`	编码联系人名片（vCard），返回字符串和二维码。
`qr_build_geo`	根据纬度和经度编码 `geo:` URI，返回字符串和二维码。

qr_build_vcard 支持这些字段：firstName（必填）、lastName、organization、phone、email 和 url。暂不支持邮寄地址、职位和备注。qr_build_geo 只接受 latitude 和 longitude（不含海拔）。

位图格式（PNG、JPG、WEBP）和 SVG 会以内联图片内容块的形式返回，因此能渲染 MCP 图片的客户端会直接在聊天中显示二维码。PDF 无法内联：本地服务器会把它写入临时文件并返回路径；远程服务器则将其作为内嵌的 application/pdf 资源返回。

前提条件

一个 API 密钥：登录 qr-branding.com，进入控制台 → API 密钥，点击生成密钥，立即复制 qrb_… 值。之后将无法再次查看，但你可以继续签发更多密钥。
Studio 套餐：API 需要有效的 Studio 额度包。使用其他任何套餐时，工具调用会以 studio_required 失败，错误会连同升级提示一起传给模型。AI 生成还会消耗 Studio 的 AI 额度（用完后返回 out_of_api_credits）。
Node 20+，仅本地服务器需要，安装在运行 MCP 进程的机器上（通常是你的笔记本电脑）。安装由 npx 完成。

远程服务器 (Streamable HTTP)

端点为 https://qr-branding.com/mcp，使用 MCP 的 Streamable HTTP 传输（无状态，返回 JSON）。可以在以下任一请求头中发送密钥：

Authorization: Bearer qrb_PASTE_YOUR_KEY（大多数客户端采用的方式）
X-API-Key: qrb_PASTE_YOUR_KEY（与 REST API 相同的请求头）

没有有效密钥的请求会收到 401，并带有 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"

在会话中运行 /mcp 确认服务器已连接，然后可以这样提问：“为 https://qr-branding.com 生成一个二维码，模块用叶形，颜色用金色”，Claude 会调用 qr_generate。

Cursor

~/.cursor/mcp.json（或 Settings → MCP）：

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

VS Code (GitHub Copilot 代理模式)

工作区中的 .vscode/mcp.json：

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

其他客户端

任何支持带自定义请求头的 Streamable HTTP 的客户端，都可以使用同样的 url + headers 组合。只能启动 stdio 服务器的客户端可以改用本地服务器。

claude.ai 和 Claude Desktop 的自定义连接器

从 claude.ai 添加的自定义连接器（网页端，以及 Claude Desktop 的“连接器”设置）使用 OAuth 认证，而 QR Branding MCP 服务器目前尚不支持 OAuth：它们无法发送 API 密钥请求头。在支持之前，请在 Claude Desktop 中使用本地服务器（见下文），或在 Claude Code 中使用远程服务器。

本地服务器 (npm, stdio)

客户端启动 npx @qr-branding/mcp-server，并通过进程的 stdin/stdout 传输 JSON-RPC。密钥放在环境变量 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)

打开配置文件：

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

完全退出 Claude Desktop 后重新打开。QR Branding 服务器应出现在消息输入框旁的工具菜单中，并显示为可用。

Cursor

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

重启 Cursor。这些工具同时对聊天中的代理和 Composer 可用。

ChatGPT Desktop

ChatGPT Desktop 读取 ~/.openai/chatgpt/mcp-config.json（路径可能因版本而异，请在 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 扩展)

在 Continue 配置（~/.continue/config.json 或工作区的 .continue/config.json）的 mcpServers 下添加：

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

Zed

打开 ~/.config/zed/settings.json，在 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" }
  }
}

环境变量 (本地服务器)

变量	默认值	何时需要修改
`QR_BRANDING_API_KEY`	（必填）	你的 `qrb_…` 密钥。未设置时，服务器会拒绝启动并给出明确的错误。
`QR_BRANDING_API_BASE_URL`	`https://qr-branding.com`	指向预发布环境或自托管网关。适合开发时使用。

验证是否正常工作

远程服务器：用 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"}'

本地服务器：在源码检出目录中运行冒烟测试：

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

冒烟测试会探测 /api/v1/qr/ping 和 /api/v1/qr/templates，打印模板数量，并且（设置 SMOKE_GENERATE=1 时）端到端生成一个很小的测试二维码。

费用与限制

生成调用：手动生成、模板和内容工具不消耗额度；使用我们的密钥进行 AI 生成（qr_generate_ai）消耗 1 个 Studio AI 额度。列表和模板元数据调用同样不消耗额度。请参阅价格与额度。
速率限制与网关一致：请参阅 API 概览。在远程服务器上，每次工具调用都按一次请求计入你的密钥的每分钟限制和每日上限；握手和 tools/list 只计入按网络的限制。
AI 助手一侧的费用取决于你所用助手的定价（Claude 用量、ChatGPT 订阅等）。MCP 服务器本身免费。

隐私与安全

MCP 服务器会把你的提示词以及传入的任何 URL 或文本转发到 qr-branding.com。没有第三方遥测，也没有分析 SDK。
API 密钥保存在客户端配置中，不会出现在聊天记录或模型上下文里。远程服务器只通过 HTTPS 接收密钥，并与哈希值比对，与 REST API 相同。
可随时在控制台 → API 密钥中轮换密钥；旧密钥会立即失效。

故障排除

"QR_BRANDING_API_KEY not set"（本地）：环境变量没有传到启动的 npx 进程。请检查 JSON 是否有效，并重启宿主应用。
401 invalid_api_key / missing_api_key（远程）：请求头没有送达，或密钥已被撤销。请检查客户端配置中的 Authorization: Bearer qrb_… 请求头。
studio_required：你的账户没有有效的 Studio 额度包（Starter 和 Pro 仅含编辑器）。请在定价页购买 Studio。
out_of_api_credits：你的 Studio AI 额度已用完。请在定价页充值。
图片没有内联显示：你的客户端可能不支持 MCP 图片内容。位图和 SVG 使用规范中的图片内容类型；PDF 会以文件路径（本地）或内嵌资源（远程）的形式返回。
网络错误 / 超时：网关位于 https://qr-branding.com。如果你的网络屏蔽了它，请覆盖 QR_BRANDING_API_BASE_URL（本地服务器）。

后续计划

我们正在为后续版本跟进这些事项：

远程服务器支持 OAuth，使其能作为自定义连接器添加到 claude.ai 以及其他要求 OAuth 的客户端。
新增 qr_dynamic_create 工具，无需离开聊天即可创建可打印的动态二维码（/q/{slug} 重定向器）。
提供资源处理程序，让模板可作为 MCP 资源浏览（带资源选择器的客户端就能在界面中展示它们）。

欢迎在代码仓库中提交问题或功能请求。该包的源码与引擎位于同一个 monorepo。