Qrblox

Qrblox MCP

适用于 Qrblox 的 Model Context Protocol 服务 — 让任何支持 MCP 的 AI Agent 都能生成和管理二维码、音频码、 菜单和忠诚度活动。

📚 完整参考文档： docs.qrblox.com/mcp.html 🌐 端点： https://app.qrblox.com/api/mcp 🔑 创建密钥： create.qrblox.com/settings/api-keys 🟢 无需密钥的沙盒： POST https://app.qrblox.com/api/generate-qr-code

这是一个仅包含 README 的公开仓库。MCP 服务本身 部署在上述端点；权威文档位于 docs.qrblox.com/mcp.html。

---

这是什么？

qrblox-mcp 是一个 JSON-RPC 2.0 MCP 服务。将 Claude Desktop、 Cursor、Codex 或任何 MCP 客户端连接到 https://app.qrblox.com/api/mcp， 填入一个 sk-qrblox- 密钥，助手便能立即为商家工作区草拟二维码 （以及音频码、菜单和忠诚度活动），并读取扫码分析数据。

通过 MCP 创建的每个码都会保存在调用者的 Qrblox 账户中， 与通过 iOS、Android、Canva 和网页端创建的码并列。

---

快速开始

1. 免费试用（无需注册，无需 OAuth）

curl -X POST https://app.qrblox.com/api/generate-qr-code \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com"}'

返回：

{
  "ok": true,
  "code": {
    "codeId": "…",
    "destinationUrl": "https://example.com",
    "qrImage":    "data:image/png;base64,…",            // inline PNG
    "qrImageUrl": "https://storage.googleapis.com/…",    // hosted PNG
    "claimToken": "…",
    "expiresAt":  "…"
  },
  "upgrade": { "signup": "https://app.qrblox.com", "apiKeys": "https://create.qrblox.com/settings/api-keys" }
}

沙盒限制：每个 IP 每天 3 个码，码会在 7 天后过期。

2. 创建 API 密钥

登录 create.qrblox.com → 设置 → API 密钥 → 新建 API 密钥。密钥格式为 sk-qrblox-<64 hex chars>，仅显示一次，可随时撤销。

3. 连接 Claude Desktop

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "qrblox": {
      "url": "https://app.qrblox.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sk-qrblox-..."
      }
    }
  }
}

重启 Claude Desktop。然后询问：“为 https://my-spring-menu.com 生成一个二维码。”

4. 或使用 Cursor / Codex / curl

URL 和 Authorization 标头相同。

# tools/list — no auth required
curl -X POST https://app.qrblox.com/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# tools/call — create a code on your account
curl -X POST https://app.qrblox.com/api/mcp \
  -H 'authorization: Bearer sk-qrblox-...' \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"qrblox.qr.create",
                 "arguments":{"title":"Spring menu",
                              "destinationUrl":"https://qrblox.com/menu/spring"}}}'

---

工具

所有工具均限定于商家范围，且先草拟——Agent 提出方案， 商家批准后才能发布。

工具	说明
qrblox.ping	确认服务可访问性和身份。
qrblox.merchant.get_profile	与密钥关联的商家工作区。
qrblox.qr.list	列出近期二维码。
qrblox.qr.create	创建二维码草稿（URL、菜单、优惠、活动）。
qrblox.audio.create	草拟音频码（近超声波载荷）。
qrblox.menu.create / .list / .add_item	创建和扩展商家菜单。
qrblox.challenge.create	创建扫码连续打卡、扫码次数游戏、限时到访或忠诚度活动。
qrblox.analytics.scan_summary	扫码总数及按日统计序列。

另外还提供两个供非 MCP 调用者使用的 REST 端点：

端点	身份验证	说明
POST /api/generate-qr-code	无	每个 IP 每天 3 个，沙盒模式，有效期 7 天。
POST /api/bulk-qr-codes	Bearer sk-qrblox-...	每次调用最多创建 50 个永久码，并写入你的商家工作区。

---

发现

URL	返回内容
GET https://app.qrblox.com/api/mcp	服务信息和完整工具列表（无需身份验证）。
POST https://app.qrblox.com/api/mcp tools/list	JSON-RPC 工具发现（无需身份验证）。
GET https://app.qrblox.com/api/generate-qr-code	公开清单：端点格式、限制和升级路径。

完整参考文档和连接示例见 docs.qrblox.com/mcp.html。

---

错误

HTTP / JSON-RPC	含义
400 / -32600	JSON-RPC 2.0 请求无效。
401 / -32001	缺少密钥或密钥无效。data.code = NO_AUTH / INVALID_API_KEY / INVALID_TOKEN。
403 / -32001	密钥已撤销（data.code = REVOKED）。
200 / -32601	不支持的方法。
200 / -32602	未知工具。
200 / -32000	工具处理程序抛出异常——请查看 error.message。

---

安全模型

• 按商户隔离 — 每个 API 密钥都关联一个商户工作区和一个所有者 uid；工具无法访问其他商户的数据。
• 密钥哈希存储 — 明文仅显示一次；Firestore 只存储 SHA-256 哈希和短前缀。
• 经过审计 — 每次工具调用都会写入一条审计记录，包含调用方、工具名称和状态。参数和结果不会持久化。
• 先创建草稿 — 创建工具会生成草稿；发布、计费和破坏性更改由商户自行处理。

---

相关链接

• 🌐 qrblox.com — 营销网站
• 🖥️ app.qrblox.com — Web 控制面板
• 📱 iOS · Android · Canva
• 📚 Qrblox 完整文档
• 🐙 Terahertz-Inc/qrblox-com — Qrblox 概览仓库

---

许可证

© Qrblox / Terahertz Inc.