QR Planet QR Code MCP Server

QR Planet QR Code MCP 服务

将 Claude Code、ChatGPT Codex、OpenCode、Google Antigravity/Gemini、Mistral Vibe 及其他兼容 MCP 的客户端连接到 QR Planet，让 AI Agent 创建、更新、设计、路由和分析动态 QR Code。

本仓库包含 QR Planet QR Code MCP 服务的文档、配置示例和提示词示例，不包含 MCP 服务的源代码。服务本身由 QR Planet 托管和运营，地址为：

https://api.qrplanet.com/mcp

这是什么？

QR Planet QR Code MCP 服务通过 Model Context Protocol（MCP）向 AI 编码 Agent 和助手开放 QR Planet 平台。

连接后，兼容 MCP 的客户端可以在聊天或 Agent 会话中直接调用 QR Planet 工具，无需手动浏览控制面板。

QR Planet MCP 服务能做什么

通过已连接的工具，AI Agent 可以：

• 创建、更新、列出和删除动态 QR Code
• 使用颜色、徽标、形状、边框和模板设计自定义 QR Code
• 根据国家、地理围栏、地理区域或语言路由 QR Code
• 管理文件夹、标签和数字名片
• 创建和管理 GS1 Digital Links 及路由规则
• 发放优惠券并查看优惠券统计数据
• 获取扫码统计数据、潜在客户信息和文件夹级分析数据
• 以及更多……

当前工具概览请参阅下方的工具。

快速开始

1. 获取 API 密钥。 登录 QR Planet 账户：qrplanet.com/premium/login，前往 API settings，打开 API v2 部分，然后点击 Show Secret API Key。

2. 复制 API 密钥。 QR Planet 密钥的格式如下：

   secret:YOUR_DOMAIN:YOUR_KEY_ID:YOUR_SECRET
   

   某些只读用例也可以使用 public: 密钥。

3. 将 MCP 服务添加到客户端。 所有客户端都连接到同一个远程 MCP 端点：

   https://api.qrplanet.com/mcp
   

4. 使用 API 密钥进行身份验证。 大多数客户端使用 HTTP 标头：

   Authorization: Bearer YOUR_QR_PLANET_API_KEY
   

5. 尝试使用提示词。

   Create a dynamic QR Code that points to https://example.com and put it in a folder called Marketing.
   

随着 MCP 客户端更新其支持，具体命令和标志可能会发生变化。如果本文档中的内容看起来过时，请查阅客户端自身的文档以及 QR Planet 官方 MCP 页面：qrplanet.com/qr-code-mcp。

配置

{
  "mcpServers": {
    "qrplanet-mcp": {
      "type": "http",
      "url": "https://api.qrplanet.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_QR_PLANET_API_KEY"
      }
    }
  }
}

设置指南

每份指南都介绍如何获取 API 密钥、如何为对应客户端添加 MCP 服务，以及如何验证连接。

客户端	指南
Claude Code	client-setup/claude-code.md
Claude Desktop / Cowork / claude.ai	client-setup/claude-apps.md
ChatGPT 网页连接器	client-setup/chatgpt-web.md
ChatGPT Codex CLI / IDE 扩展	client-setup/chatgpt-codex.md
OpenCode	client-setup/opencode.md
Google Antigravity / Gemini	client-setup/google-gemini-antigravity.md
Mistral Vibe Code CLI	client-setup/mistral-vibe.md
Mistral Work / Studio 连接器	client-setup/mistral-work-studio.md

确认设置步骤后，我们会继续添加更多客户端指南。

示例提示词

prompts/ 中提供了可直接使用的常见任务提示词：

• 创建动态 QR Code
• 创建品牌化 QR Code 设计
• 创建静态 QR Code
• 更新营销活动的目标 URL
• 根据位置或语言路由 QR Code 目标
• 管理 QR Code 标签
• 管理 QR Code 文件夹
• 分析扫码统计数据
• 导出 QR Code 潜在客户信息
• 创建数字名片
• 创建 GS1 Digital Link QR Code
• 发放优惠券
• 更新 App Store QR Code 目标

工具

QR Planet MCP 服务目前提供以下工具。工具是否可用可能取决于你的 QR Planet API 密钥权限，且也可能随时间变化。当然，唯一权威来源是客户端实时返回的 MCP tools/list 响应。

QR 码

• create_qr_code — 创建动态 QR 码
• list_qr_codes — 列出 QR 码
• get_qr_code — 按代码获取 QR 码
• update_qr_code — 更新 QR 码字段，例如目标 URL、标题、元数据、文件夹或设置
• delete_qr_code — 删除 QR 码
• get_qr_code_stats — 获取 QR 码扫描统计数据
• reset_qr_code_stats — 重置 QR 码扫描统计数据
• get_qr_code_leads — 获取通过 QR 码落地页收集的潜在客户信息

QR 码标签

• get_qr_code_tags — 获取分配给 QR 码的标签
• update_qr_code_tags — 替换或更新 QR 码上的标签
• delete_qr_code_tags — 移除 QR 码的所有标签

QR 码定向

• add_qr_code_country_target — 添加特定国家/地区的目标 URL
• delete_qr_code_country_target — 移除特定国家/地区的目标
• add_qr_code_language_target — 添加特定语言的目标 URL
• delete_qr_code_language_target — 移除特定语言的目标
• add_qr_code_geofence_target — 添加特定地理围栏的目标 URL
• delete_qr_code_geofence_target — 移除特定地理围栏的目标
• add_qr_code_georegion_target — 添加特定地理区域的目标 URL
• delete_qr_code_georegion_target — 移除特定地理区域的目标

QR 码设计

• design_qr_code — 为现有动态 QR 码应用自定义设计
• design_static_qr_code — 根据静态内容创建经过设计的静态 QR 码
• create_designer_template — 创建可重复使用的 QR 码设计器模板
• get_designer_template — 按 ID 获取设计器模板
• list_designer_templates — 列出设计器模板

App Store QR 码

• update_app_store_qr_code_targets — 更新 App Store QR 码的目标 URL

数字名片

• create_digital_business_card — 创建数字名片
• list_digital_business_cards — 列出数字名片
• get_digital_business_card — 按代码获取数字名片
• update_digital_business_card — 更新数字名片字段
• delete_digital_business_card — 删除数字名片
• upload_digital_business_card_image — 为数字名片上传头像、徽标或背景图片

文件夹

• create_folder — 创建文件夹
• list_folders — 列出文件夹
• get_folder — 按 ID 获取文件夹
• delete_folder — 删除文件夹
• get_folder_stats — 获取文件夹级别的扫描统计数据
• reset_folder_stats — 重置文件夹级别的扫描统计数据

GS1 Digital Link

• create_gs1_digital_link — 创建 GS1 Digital Link QR 码
• create_gs1_digital_link_rule — 为 GS1 Digital Link QR 码创建路由规则
• list_gs1_digital_link_rules — 列出 GS1 Digital Link QR 码的规则
• delete_gs1_digital_link_rules — 删除 GS1 Digital Link QR 码的所有规则

优惠券与代金券

• list_coupons — 列出优惠券
• issue_coupon_voucher — 为优惠券发放代金券
• get_coupon_issue_stats — 获取优惠券发放统计数据
• get_coupon_redemptions — 获取优惠券兑换统计数据

API 密钥与安全

请像对待密码一样保护你的 QR Planet API 密钥。

• 切勿将其提交到代码仓库
• 切勿将其粘贴到共享聊天中
• 切勿在公开配置示例中硬编码
• 优先使用环境变量或客户端的密钥存储
• 只有在读取权限足够时才使用 public: 密钥
• 对于创建、更新或删除资源的操作流程，请使用 secret: 密钥
• 如果密钥泄露，请立即轮换

环境变量示例：

export QR_PLANET_API_KEY="secret:YOUR_DOMAIN:YOUR_KEY_ID:YOUR_SECRET"

故障排除

如果 MCP 客户端无法连接：

• 检查服务 URL 是否准确为 https://api.qrplanet.com/mcp
• 如果这符合客户端的模式，请检查 Authorization 标头是否以 Bearer 开头（请参阅设置指南）
• 确认 API 密钥在 QR Planet API 设置中有效
• 确认客户端支持远程 MCP 服务
• 运行客户端的 MCP 工具发现命令，并验证 tools/list 是否返回 QR Planet 工具

如果身份验证失败，请重新生成 API 密钥并更新客户端配置。

官方文档

本仓库补充了 QR Planet MCP 官方文档：

qrplanet.com/qr-code-mcp

许可证

本仓库采用 MIT License 许可。您可以自由使用、复制、修改和分享本文档、配置示例和提示词示例，但须遵守许可证条款。