QR Agent Core

Name: QR for Agent
Author: benswel

benswel/qr-agent-core MCP server

专为 AI Agent 构建的 QR-as-a-Service（二维码即服务）API。通过 REST API 或 MCP（37 个工具）以编程方式创建、更新和追踪动态二维码。

二维码指向短链接 (/r/:shortId)，您可以随时更改其目标地址——二维码图像本身保持不变，但扫描后会跳转到新的目标。采用多租户设计，并提供完整的扫描分析功能。

实时 API： api.qragentcore.com | 网站： qrforagent.com | MCP： qr-for-agent

功能特性

动态二维码 — 无需重新生成图像即可更改目标 URL
11 种二维码类型 — URL、vCard、WiFi、电子邮件、短信、电话、活动、文本、位置、社交媒体、应用商店
自定义样式 — 点形状（方形、圆形、圆点、经典圆角）、角样式、颜色、渐变、嵌入 Logo、带 CTA 文字的边框
SVG & PNG — 支持矢量图和位图输出
丰富的分析数据 — 设备类型、浏览器、操作系统、国家、城市、引荐来源、每日扫描量
实时 Webhook — 带有 HMAC-SHA256 签名负载及投递日志
UTM 追踪 — 自动为重定向 URL 添加 UTM 参数
GTM 支持 — 带有 Google Tag Manager 代码片段的中间页
条件重定向 — 根据设备、操作系统、国家、语言、时间范围或 A/B 分流进行路由
自定义域名 — Pro 用户可以使用自己的域名为短链接打标 (qr.yourbrand.com/r/abc123)
过期与定时 — 自动设置二维码过期或定时切换 URL
转化追踪 — 追踪像素 + 用于扫描后事件（购买、注册）的 API，并提供 ROI 分析
边框与模板 — 二维码周围的装饰性边框（顶部横幅、底部横幅、圆角）及 CTA 文字
批量操作 — 每个请求最多可创建、更新或删除 50 个二维码，通过 CSV 上传最多可处理 500 个（Pro 版）
多租户 — 每个 API Key 仅能查看其自身数据
MCP 服务器 — qr-for-agent，为 Claude Desktop、Cursor 等提供 37 个工具
基于计划的配额 — 免费版（10 个二维码，每月 1K 次扫描）和 Pro 版（19 美元/月，无限制）
自助注册 — 通过 POST /api/register 使用邮箱注册，无需信用卡
Stripe 集成 — 结账、计费门户、基于 Webhook 的计划管理
OpenAPI 文档 — /documentation 处的 Swagger UI
AI 可发现 — /.well-known/ai-plugin.json 和 /.well-known/mcp.json
开源 — MIT 许可证，可通过 Docker 自托管

Related MCP server: QR Code Generator MCP

快速开始

git clone https://github.com/benswel/qr-agent-core.git
cd qr-agent-core
npm install
npm run dev

首次启动时，系统会自动生成一个 API Key 并打印到控制台。

curl -X POST http://localhost:3100/api/qr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY_HERE" \
  -d '{"target_url": "https://example.com", "label": "My first QR"}'

API 端点

二维码管理（需要 `X-API-Key`）

方法	路径	描述
`POST`	`/api/qr`	创建二维码（11 种类型，自定义样式）
`GET`	`/api/qr`	列出所有二维码（分页）
`GET`	`/api/qr/:shortId`	获取二维码详情
`PATCH`	`/api/qr/:shortId`	更新目标 URL、标签、UTM、GTM、重定向规则
`DELETE`	`/api/qr/:shortId`	删除二维码及其分析数据
`GET`	`/api/qr/:shortId/image`	下载二维码图像（使用存储的样式重新生成）
`POST`	`/api/qr/bulk`	批量创建最多 50 个二维码（全有或全无）
`PATCH`	`/api/qr/bulk`	批量更新最多 50 个二维码（部分成功）
`DELETE`	`/api/qr/bulk`	批量删除最多 50 个二维码（部分成功）
`POST`	`/api/qr/bulk/csv`	从 CSV 创建最多 500 个二维码（仅限 Pro）

分析（需要 `X-API-Key`）

方法	路径	描述
`GET`	`/api/analytics/:shortId`	扫描统计，包含设备、浏览器、操作系统、国家、城市细分及转化数据

转化（需要 `X-API-Key`）

方法	路径	描述
`POST`	`/api/conversions`	记录您拥有的二维码的转化事件
`GET`	`/api/conversions/:shortId`	获取转化统计（总计、按事件、按天、最近）

Webhook（需要 `X-API-Key`）

方法	路径	描述
`POST`	`/api/webhooks`	注册 Webhook 端点（返回 HMAC 密钥）
`GET`	`/api/webhooks`	列出所有 Webhook
`DELETE`	`/api/webhooks/:id`	删除 Webhook

自定义域名（需要 `X-API-Key`，仅限 Pro）

方法	路径	描述
`GET`	`/api/domain`	获取当前自定义域名及 DNS 状态
`PUT`	`/api/domain`	设置自定义域名
`DELETE`	`/api/domain`	移除自定义域名

账户（需要 `X-API-Key`）

方法	路径	描述
`GET`	`/api/usage`	当前使用量和配额
`POST`	`/api/stripe/checkout`	创建 Stripe 结账会话（升级至 Pro）
`POST`	`/api/stripe/portal`	打开 Stripe 计费门户

公共端点（无需认证）

方法	路径	描述
`POST`	`/api/register`	自助 API Key 注册（受速率限制）
`GET`	`/r/:shortId`	重定向至目标 URL（记录扫描）
`GET`	`/t/:shortId`	转化追踪像素（返回 1×1 GIF）
`GET`	`/i/:shortId`	提供二维码图像（可缓存）
`GET`	`/health`	健康检查
`GET`	`/documentation`	Swagger UI
`GET`	`/.well-known/ai-plugin.json`	AI 插件清单
`GET`	`/.well-known/mcp.json`	MCP 发现清单

管理员（需要 `X-Admin-Secret` 请求头）

方法	路径	描述
`GET`	`/api/admin/keys`	列出所有已注册的 API Key
`GET`	`/api/admin/stats`	仪表盘指标

认证

所有 /api/* 端点都需要 X-API-Key 请求头。

格式：qr_ + 32 位随机字符串
自动生成：如果不存在密钥，则在首次启动时生成
多租户：每个密钥只能看到其自己的二维码
创建密钥：npm run key:create "my-label"
列出密钥：npm run key:list

公共端点（/r/*, /i/*, /health, /documentation, /.well-known/*）不需要认证。

MCP 服务器

以 qr-for-agent 发布在 npm 上。为 AI Agent 提供 37 个工具以原生管理二维码。

npx qr-for-agent

Claude Desktop / Cursor

添加到您的 MCP 配置（claude_desktop_config.json 或 .cursor/mcp.json）：

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "your-api-key",
        "BASE_URL": "https://api.qragentcore.com"
      }
    }
  }
}

可用工具 (37)

工具	描述
`create_qr_code`	创建带有可选自定义样式的 URL 二维码
`get_qr_code`	通过短 ID 获取二维码详情
`update_qr_destination`	更改二维码的重定向目标
`list_qr_codes`	列出所有二维码（分页）
`delete_qr_code`	删除二维码及其分析数据
`get_qr_analytics`	获取扫描统计和细分数据
`bulk_create_qr_codes`	一次性创建最多 50 个二维码
`bulk_update_qr_codes`	一次性更新最多 50 个二维码
`bulk_delete_qr_codes`	一次性删除最多 50 个二维码
`create_vcard_qr`	创建 vCard 联系人二维码
`create_wifi_qr`	创建 WiFi 凭据二维码
`create_email_qr`	创建电子邮件 (mailto:) 二维码
`create_sms_qr`	创建短信二维码
`create_phone_qr`	创建电话呼叫二维码
`create_event_qr`	创建日历事件二维码
`create_text_qr`	创建纯文本二维码
`create_location_qr`	创建地理位置二维码
`create_social_qr`	创建社交媒体链接二维码
`create_app_store_qr`	创建智能应用商店重定向二维码
`update_vcard_qr`	更新 vCard 二维码
`update_wifi_qr`	更新 WiFi 二维码
`update_social_qr`	更新社交媒体二维码
`update_app_store_qr`	更新应用商店二维码
`create_webhook`	注册 Webhook 端点
`list_webhooks`	列出所有已注册的 Webhook
`delete_webhook`	删除 Webhook
`register`	注册 API Key
`get_usage`	获取当前使用量和配额
`upgrade_to_pro`	创建 Stripe 结账会话
`manage_billing`	打开 Stripe 计费门户
`set_utm_params`	设置二维码的 UTM 追踪参数
`set_redirect_rules`	设置二维码的条件重定向规则
`set_custom_domain`	设置或移除自定义域名 (Pro)
`get_custom_domain`	获取当前自定义域名及 DNS 状态
`bulk_create_from_csv`	从 CSV 数据创建最多 500 个二维码 (Pro)
`record_conversion`	记录扫描后的转化事件
`get_conversions`	获取二维码的转化统计

配置

将 .env.example 复制为 .env 并编辑：

变量	默认值	描述
`PORT`	`3100`	HTTP 端口
`HOST`	`0.0.0.0`	绑定地址
`BASE_URL`	`http://localhost:3100`	公共 URL（用于短链接）
`DATABASE_URL`	`./data/qr-agent.db`	SQLite 文件路径
`SHORT_ID_LENGTH`	`8`	生成的短 ID 长度
`ADMIN_SECRET`	(无)	管理员端点密钥 (`X-Admin-Secret` 请求头)
`STRIPE_SECRET_KEY`	(无)	Stripe API 密钥
`STRIPE_WEBHOOK_SECRET`	(无)	Stripe Webhook 签名密钥
`STRIPE_PRICE_ID`	(无)	Pro 计划的 Stripe 价格 ID

数据库

使用 Drizzle ORM 的 SQLite。包含六张表：

api_keys — 密钥存储，包含标签、邮箱、计划（免费/Pro）、Stripe ID、自定义域名
qr_codes — 二维码元数据、目标 URL、类型/类型数据、样式选项、UTM、GTM、重定向规则、过期/定时设置
scan_events — 扫描追踪：时间戳、User-Agent、引荐来源、IP、设备、浏览器、操作系统、国家、城市
webhooks — 每个 API Key 的 Webhook 端点、HMAC 密钥、订阅事件
webhook_deliveries — 投递日志：状态、响应代码、错误消息
conversion_events — 转化追踪：事件名称、值、元数据、引荐来源、IP、时间戳

npm run db:generate   # Generate migration from schema changes
npm run db:migrate    # Apply pending migrations
npm run db:studio     # Open Drizzle Studio (web UI)

迁移脚本会在服务器启动时自动运行。

部署

Docker

docker compose up -d

数据库持久化在 Docker 卷中。

Railway

该项目包含 railway.toml 和多阶段 Dockerfile。将您的 GitHub 仓库连接到 Railway，它会自动构建并部署，并对 /health 进行健康检查。

测试

195 个集成测试，涵盖所有端点、认证、多租户隔离、二维码类型、Webhook、批量操作、自定义域名、边框、转化、CSV 上传和分析。

npm test           # Run all tests
npm run test:watch # Watch mode

脚本

脚本	描述
`npm run dev`	启动开发服务器并自动重载
`npm run build`	编译 TypeScript
`npm start`	运行生产服务器
`npm test`	运行测试套件
`npm run test:watch`	监视模式运行测试
`npm run key:create`	创建 API Key
`npm run key:list`	列出 API Key
`npm run db:generate`	生成迁移文件
`npm run db:migrate`	运行迁移
`npm run db:studio`	打开 Drizzle Studio

许可证

MIT

QR for Agent

QR Agent Core

功能特性

快速开始

API 端点

二维码管理（需要 `X-API-Key`）

分析（需要 `X-API-Key`）

转化（需要 `X-API-Key`）

Webhook（需要 `X-API-Key`）

自定义域名（需要 `X-API-Key`，仅限 Pro）

账户（需要 `X-API-Key`）

公共端点（无需认证）

管理员（需要 `X-Admin-Secret` 请求头）

认证

MCP 服务器

Claude Desktop / Cursor

可用工具 (37)

配置

数据库

部署

Docker

Railway

测试

脚本

许可证

Resources

Tools

Latest Blog Posts

MCP directory API

QR Agent Core

功能特性

快速开始

API 端点

二维码管理（需要 X-API-Key）

分析（需要 X-API-Key）

转化（需要 X-API-Key）

Webhook（需要 X-API-Key）

自定义域名（需要 X-API-Key，仅限 Pro）

账户（需要 X-API-Key）

公共端点（无需认证）

管理员（需要 X-Admin-Secret 请求头）

认证

MCP 服务器

Claude Desktop / Cursor

可用工具 (37)

配置

数据库

部署

Docker

Railway

测试

脚本

许可证

Resources

Tools

Latest Blog Posts

MCP directory API

二维码管理（需要 `X-API-Key`）

分析（需要 `X-API-Key`）

转化（需要 `X-API-Key`）

Webhook（需要 `X-API-Key`）

自定义域名（需要 `X-API-Key`，仅限 Pro）

账户（需要 `X-API-Key`）

管理员（需要 `X-Admin-Secret` 请求头）