CodeBoxCodeBox 文档

MCP Server

通过 MCP 协议接入 Claude Desktop、Cursor 等 AI Agent，直接调用二维码生成、追踪分析等能力

简介

CodeBox 提供 MCP（Model Context Protocol） Server，让 AI Agent（Claude Desktop、Cursor、Windsurf 等）直接调用二维码生成、追踪分析、动态链接更新和模板浏览能力。

协议：Streamable HTTP（无状态模式）

端点：

POST https://www.codebox.club/api/mcp

认证

CodeBox MCP 同时支持 OAuth 登录和 API Key。Codex Plugin 默认使用 OAuth：浏览器已有 CodeBox 会话时直接连接，未登录时复用现有微信扫码登录。

其他客户端仍可使用 API Key：

Authorization: Bearer cb_sk_xxxxxxxxxxxxxxxx

API Key 可在 Dashboard → API 管理 中创建，需要包含 qrcode:generate 权限。详见鉴权文档。

快速接入

Codex（推荐使用 Plugin）

CodeBox Codex Plugin 在 MCP 工具之上增加场景识别、模板搜索、模式推荐、积分确认和连续修改流程。安装后无需配置 API Key，首次使用按提示登录 CodeBox 即可。参见 Codex Plugin 安装指南。

也可以让支持 MCP OAuth 的客户端直接连接并启动浏览器登录：

codex mcp add codebox --url https://www.codebox.club/api/mcp
codex mcp login codebox

服务端提供 OAuth Protected Resource Metadata、Authorization Server Metadata、动态客户端注册、PKCE、刷新令牌轮换和撤销端点。

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "codebox-qrcode": {
      "url": "https://www.codebox.club/api/mcp",
      "headers": {
        "Authorization": "Bearer cb_sk_你的API_KEY"
      }
    }
  }
}

Cursor

在 Cursor 设置中添加 MCP Server：

  • Name: codebox-qrcode
  • Type: Streamable HTTP
  • URL: https://www.codebox.club/api/mcp
  • Headers: Authorization: Bearer cb_sk_你的API_KEY

MCP Inspector 测试

npx @modelcontextprotocol/inspector

连接到 https://www.codebox.club/api/mcp，设置 Authorization header。

可用工具

MCP Server 提供 9 个 Tool：

open_editor

启动 CodeBox 完整编辑器，用于首次引导或用户尚未提供二维码内容的场景。该工具不创建二维码、不占用静态码额度，也不消耗积分。

参数：无。

返回：

{
  "editorUrl": "https://www.codebox.club/zh/editor?source=codex",
  "createsQRCode": false,
  "consumesQuota": false,
  "costsPoints": false,
  "browserHandoff": {
    "required": true,
    "url": "https://www.codebox.club/zh/editor?source=codex",
    "preferredMode": "codex-internal-browser",
    "reuseCurrentCodeBoxTab": true
  }
}

Codex Plugin 收到 handoff 后先打开或复用 CodeBox 编辑器标签页，在对话中介绍能力并询问用户已有素材和目标；只有拿到具体内容并完成必要确认后才调用 generate。

generate

生成带追踪的二维码，支持动态/静态模式和智能模板匹配。DYNAMIC 模式消耗 10 积分，STATIC 模式不消耗积分但占用当月静态码配额。

参数：

参数类型必填说明
contentstring是要编码的 URL 或文本
modestring否DYNAMIC（默认）或 STATIC
namestring否二维码名称
templateIdstring否模板 ID（通过 list_templates 获取）
keywordsstring[]否自动匹配模板的关键词
errorCorrectionLevelstring否L、M（默认）、Q、H
foregroundColorstring否精确前景色，#RRGGBB
backgroundColorstring否精确背景色，#RRGGBB
dotTypestring否rounded、square、dots 或 classy-rounded
sizenumber否内置浏览器预览及导出尺寸，256–1600，默认 1024

返回：

{
  "id": "clxxx...",
  "shortLink": "https://www.codebox.club/s/AbCdEf",
  "templateUsed": "tech-modern-01",
  "matchedKeywords": ["科技"],
  "mode": "DYNAMIC",
  "agentUrl": "https://www.codebox.club/zh/editor?...",
  "browserHandoff": {
    "required": true,
    "url": "https://www.codebox.club/zh/editor?...",
    "preferredMode": "codex-internal-browser",
    "reuseCurrentCodeBoxTab": true
  }
}

Codex Plugin 收到 browserHandoff 后会优先复用当前 CodeBox 编辑器标签页，使 MCP 创建的真实二维码立即显示在内置浏览器中。 source=codex 直接加载官网现有二维码编辑器及其完整预览和样式能力，不展示 Agent 对话栏。用户在页面修改常用视觉参数时会自动保存到同一二维码，后续 MCP 更新以同一 ID 为基础合并修改。旧版 /agent?source=codex 链接会兼容跳转到编辑器。

CodeBox 未连接时，应使用 Codex MCP Host 提供的 OAuth 授权提示并在授权后恢复原始工具调用。已有 CodeBox Session 时直接完成授权；否则在内置浏览器显示现有微信扫码登录。不要把 CLI 本机回调或私人 API Key 作为 Codex Plugin 的用户流程。

get_stats

查询二维码扫描统计，包括总量、设备、浏览器、地域分布。

参数：

参数类型必填说明
qrCodeIdstring是二维码 ID
startDatestring否起始日期 YYYY-MM-DD（默认 30 天前）
endDatestring否结束日期 YYYY-MM-DD（默认今天）

返回：

{
  "totalScans": 1234,
  "uniqueUsers": 890,
  "deviceBreakdown": { "mobile": 72.5, "desktop": 22.3, "tablet": 5.2 },
  "dailyScans": [{ "date": "2026-03-01", "count": 45 }],
  "topBrowsers": [{ "browser": "Chrome", "count": 500 }],
  "topOS": [{ "os": "iOS", "count": 400 }],
  "geoData": [{ "country": "CN", "region": "Shanghai", "city": "Shanghai", "count": 200 }]
}

除目标链接、名称和状态外，update_link 还支持 foregroundColor、backgroundColor、dotType、errorCorrectionLevel 和 size。视觉参数不会创建新二维码；成功后返回新的 browserHandoff，客户端应复用当前 CodeBox 标签页刷新同一个项目。

更新动态二维码的目标 URL、名称或状态。

参数：

参数类型必填说明
idstring是二维码 ID
targetUrlstring否新的目标 URL
namestring否新名称
statusstring否READY、EXPIRED、DELETED
foregroundColorstring否新前景色，#RRGGBB
backgroundColorstring否新背景色，#RRGGBB
dotTypestring否rounded、square、dots、classy-rounded
errorCorrectionLevelstring否L、M、Q、H
sizenumber否当前预览与导出尺寸，256–1600

list_templates

浏览可用的二维码风格模板。

参数：

参数类型必填说明
categorystring否按类别筛选
keywordstring否搜索关键词
limitnumber否返回数量（默认 20）

list_qrcodes

查询用户的二维码列表，支持分页和筛选。

参数：

参数类型必填说明
pagenumber否页码（默认 1）
sizenumber否每页数量，最大 50（默认 10）
modestring否按模式筛选：STATIC / DYNAMIC / AI
keywordstring否按名称或描述搜索

返回：

{
  "pagination": { "page": 1, "size": 10, "total": 42, "totalPages": 5 },
  "qrcodes": [
    {
      "id": "clxxx...",
      "name": "营销码",
      "mode": "DYNAMIC",
      "status": "READY",
      "targetUrl": "https://example.com",
      "scanCount": 128,
      "createdAt": "2026-03-01T00:00:00Z"
    }
  ]
}

delete_qrcode

软删除二维码。二维码必须属于当前用户。

参数：

参数类型必填说明
idstring是要删除的二维码 ID

返回：

{
  "id": "clxxx...",
  "deleted": true,
  "message": "QR code has been deleted successfully"
}

batch_generate

批量生成二维码（最多 20 个），支持 partial failure。每个 item 独立处理，部分失败不影响其他 item。每个动态 item 消耗 10 积分，静态码不消耗积分但占用当月静态码配额。

参数：

参数类型必填说明
itemsarray是二维码配置数组（最多 20 个）

每个 item 的参数与 generate 工具相同（content, mode, name, templateId, keywords, errorCorrectionLevel）。

返回：

{
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "index": 0, "success": true, "data": { "id": "cl1...", "shortLink": "https://...", "templateUsed": "default" } },
    { "index": 1, "success": true, "data": { "id": "cl2...", "templateUsed": "tech-modern-01" } },
    { "index": 2, "success": false, "error": "Template \"invalid\" not found" }
  ]
}

export_scans

导出二维码的原始扫描事件，支持分页和日期筛选。

参数：

参数类型必填说明
qrCodeIdstring是二维码 ID
pagenumber否页码（默认 1）
sizenumber否每页数量，最大 100（默认 20）
startDatestring否起始日期 YYYY-MM-DD
endDatestring否结束日期 YYYY-MM-DD

返回：

{
  "qrCodeId": "clxxx...",
  "pagination": { "page": 1, "size": 20, "total": 156, "totalPages": 8 },
  "events": [
    {
      "id": "evt_xxx",
      "eventType": "impression",
      "device": "Mobile",
      "os": "iOS",
      "browser": "Safari",
      "country": "中国",
      "region": "上海",
      "city": "上海",
      "timestamp": "2026-03-10T12:30:00Z"
    }
  ]
}

curl 测试

初始化连接

curl -X POST https://www.codebox.club/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cb_sk_xxx" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

调用 list_templates

curl -X POST https://www.codebox.club/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cb_sk_xxx" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_templates","arguments":{"limit":3}}}'

调用 generate

curl -X POST https://www.codebox.club/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cb_sk_xxx" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"generate","arguments":{"content":"https://example.com","mode":"DYNAMIC","name":"测试二维码"}}}'

调用 list_qrcodes

curl -X POST https://www.codebox.club/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cb_sk_xxx" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_qrcodes","arguments":{"page":1,"size":5}}}'

调用 batch_generate

curl -X POST https://www.codebox.club/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cb_sk_xxx" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"batch_generate","arguments":{"items":[{"content":"https://example1.com","name":"批量1"},{"content":"https://example2.com","name":"批量2"}]}}}'

OpenClaw Skill

CodeBox 也发布了 OpenClaw Skill，可通过 ClawHub 安装：

clawhub install codebox-qrcode

OpenClaw Skill 包含免费的二维码图片生成（无需 API Key）和全部高级功能。

错误处理

场景处理方式
鉴权失败（401/403/429）HTTP 层直接返回错误，不进入 MCP 协议
额度不足Tool 返回 isError: true，code 为 CREDIT_EXHAUSTED
参数错误 / 资源不存在Tool 返回 isError: true，包含 error 和 code
服务器内部错误Tool 返回通用错误信息

批量操作

使用 CodeBox API 和 SDK 进行批量二维码生成，了解限制、错误处理和最佳实践

Codex Plugin

在 Codex 中通过对话创建、修改和分析二维码，内置场景工作流与 CodeBox MCP

On this page

简介认证快速接入Codex（推荐使用 Plugin）Claude DesktopCursorMCP Inspector 测试可用工具open_editorgenerateget_statsupdate_linklist_templateslist_qrcodesdelete_qrcodebatch_generateexport_scanscurl 测试初始化连接调用 list_templates调用 generate调用 list_qrcodes调用 batch_generateOpenClaw Skill错误处理