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

认证

所有 MCP 请求需要 API Key：

Authorization: Bearer cb_sk_xxxxxxxxxxxxxxxx

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

快速接入

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 提供 8 个 Tool：

generate

生成带追踪的二维码，支持动态/静态模式和智能模板匹配。DYNAMIC 模式消耗 1 次额度，STATIC 模式不消耗。

参数：

参数	类型	必填	说明
content	string	是	要编码的 URL 或文本
mode	string	否	`DYNAMIC`（默认）或 `STATIC`
name	string	否	二维码名称
templateId	string	否	模板 ID（通过 list_templates 获取）
keywords	string[]	否	自动匹配模板的关键词
errorCorrectionLevel	string	否	`L`、`M`（默认）、`Q`、`H`

{
  "id": "clxxx...",
  "shortLink": "https://www.codebox.club/s/AbCdEf",
  "templateUsed": "tech-modern-01",
  "matchedKeywords": ["科技"],
  "mode": "DYNAMIC"
}

get_stats

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

参数：

参数	类型	必填	说明
qrCodeId	string	是	二维码 ID
startDate	string	否	起始日期 YYYY-MM-DD（默认 30 天前）
endDate	string	否	结束日期 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

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

参数：

参数	类型	必填	说明
id	string	是	二维码 ID
targetUrl	string	否	新的目标 URL
name	string	否	新名称
status	string	否	`READY`、`EXPIRED`、`DELETED`

list_templates

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

参数：

参数	类型	必填	说明
category	string	否	按类别筛选
keyword	string	否	搜索关键词
limit	number	否	返回数量（默认 20）

list_qrcodes

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

参数：

参数	类型	必填	说明
page	number	否	页码（默认 1）
size	number	否	每页数量，最大 50（默认 10）
mode	string	否	按模式筛选：`STATIC` / `DYNAMIC` / `AI`
keyword	string	否	按名称或描述搜索

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

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

参数：

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

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

batch_generate

批量生成二维码（最多 20 个），支持 partial failure。每个 item 独立处理，部分失败不影响其他 item。每个非静态 item 消耗 1 次额度，静态码不消耗。

参数：

参数	类型	必填	说明
items	array	是	二维码配置数组（最多 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

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

参数：

参数	类型	必填	说明
qrCodeId	string	是	二维码 ID
page	number	否	页码（默认 1）
size	number	否	每页数量，最大 100（默认 20）
startDate	string	否	起始日期 YYYY-MM-DD
endDate	string	否	结束日期 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 返回通用错误信息

On this page