QR for Agent
QR Agent Core
专为 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 UIAI 可发现 —
/.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)
方法 | 路径 | 描述 |
|
| 创建二维码(11 种类型,自定义样式) |
|
| 列出所有二维码(分页) |
|
| 获取二维码详情 |
|
| 更新目标 URL、标签、UTM、GTM、重定向规则 |
|
| 删除二维码及其分析数据 |
|
| 下载二维码图像(使用存储的样式重新生成) |
|
| 批量创建最多 50 个二维码(全有或全无) |
|
| 批量更新最多 50 个二维码(部分成功) |
|
| 批量删除最多 50 个二维码(部分成功) |
|
| 从 CSV 创建最多 500 个二维码(仅限 Pro) |
分析(需要 X-API-Key)
方法 | 路径 | 描述 |
|
| 扫描统计,包含设备、浏览器、操作系统、国家、城市细分及转化数据 |
转化(需要 X-API-Key)
方法 | 路径 | 描述 |
|
| 记录您拥有的二维码的转化事件 |
|
| 获取转化统计(总计、按事件、按天、最近) |
Webhook(需要 X-API-Key)
方法 | 路径 | 描述 |
|
| 注册 Webhook 端点(返回 HMAC 密钥) |
|
| 列出所有 Webhook |
|
| 删除 Webhook |
自定义域名(需要 X-API-Key,仅限 Pro)
方法 | 路径 | 描述 |
|
| 获取当前自定义域名及 DNS 状态 |
|
| 设置自定义域名 |
|
| 移除自定义域名 |
账户(需要 X-API-Key)
方法 | 路径 | 描述 |
|
| 当前使用量和配额 |
|
| 创建 Stripe 结账会话(升级至 Pro) |
|
| 打开 Stripe 计费门户 |
公共端点(无需认证)
方法 | 路径 | 描述 |
|
| 自助 API Key 注册(受速率限制) |
|
| 重定向至目标 URL(记录扫描) |
|
| 转化追踪像素(返回 1×1 GIF) |
|
| 提供二维码图像(可缓存) |
|
| 健康检查 |
|
| Swagger UI |
|
| AI 插件清单 |
|
| MCP 发现清单 |
管理员(需要 X-Admin-Secret 请求头)
方法 | 路径 | 描述 |
|
| 列出所有已注册的 API Key |
|
| 仪表盘指标 |
认证
所有 /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-agentClaude 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)
工具 | 描述 |
| 创建带有可选自定义样式的 URL 二维码 |
| 通过短 ID 获取二维码详情 |
| 更改二维码的重定向目标 |
| 列出所有二维码(分页) |
| 删除二维码及其分析数据 |
| 获取扫描统计和细分数据 |
| 一次性创建最多 50 个二维码 |
| 一次性更新最多 50 个二维码 |
| 一次性删除最多 50 个二维码 |
| 创建 vCard 联系人二维码 |
| 创建 WiFi 凭据二维码 |
| 创建电子邮件 (mailto:) 二维码 |
| 创建短信二维码 |
| 创建电话呼叫二维码 |
| 创建日历事件二维码 |
| 创建纯文本二维码 |
| 创建地理位置二维码 |
| 创建社交媒体链接二维码 |
| 创建智能应用商店重定向二维码 |
| 更新 vCard 二维码 |
| 更新 WiFi 二维码 |
| 更新社交媒体二维码 |
| 更新应用商店二维码 |
| 注册 Webhook 端点 |
| 列出所有已注册的 Webhook |
| 删除 Webhook |
| 注册 API Key |
| 获取当前使用量和配额 |
| 创建 Stripe 结账会话 |
| 打开 Stripe 计费门户 |
| 设置二维码的 UTM 追踪参数 |
| 设置二维码的条件重定向规则 |
| 设置或移除自定义域名 (Pro) |
| 获取当前自定义域名及 DNS 状态 |
| 从 CSV 数据创建最多 500 个二维码 (Pro) |
| 记录扫描后的转化事件 |
| 获取二维码的转化统计 |
配置
将 .env.example 复制为 .env 并编辑:
变量 | 默认值 | 描述 |
|
| HTTP 端口 |
|
| 绑定地址 |
|
| 公共 URL(用于短链接) |
|
| SQLite 文件路径 |
|
| 生成的短 ID 长度 |
| (无) | 管理员端点密钥 ( |
| (无) | Stripe API 密钥 |
| (无) | Stripe Webhook 签名密钥 |
| (无) | 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脚本
脚本 | 描述 |
| 启动开发服务器并自动重载 |
| 编译 TypeScript |
| 运行生产服务器 |
| 运行测试套件 |
| 监视模式运行测试 |
| 创建 API Key |
| 列出 API Key |
| 生成迁移文件 |
| 运行迁移 |
| 打开 Drizzle Studio |
许可证
MIT
Available Tools
37 toolsbulk_create_from_csvA
Create up to 500 QR codes from CSV data. Pro plan required. Send the CSV content as a string. Required column: target_url. Optional columns: label, format, type, foreground_color, background_color, dot_style, corner_style, frame_style, frame_text, expires_at. Returns all created QR codes.
Inputs: csv_content (required).
bulk_create_qr_codesA
Create multiple QR codes in a single request (up to 50). Each item supports the same options as create_qr_code. The quota check is all-or-nothing: if the batch would exceed your plan limit, no QR codes are created. Ideal for generating QR codes for product catalogs, event lists, or batch operations.
Inputs: items (required).
bulk_delete_qr_codesA
Delete multiple QR codes and their scan analytics in a single request (up to 50). Items with non-existent short_id are reported as not_found without failing the whole batch.
Inputs: short_ids (required).
bulk_update_qr_codesA
Update multiple QR codes in a single request (up to 50). Change target URLs and/or labels. Items with non-existent short_id are reported as not_found without failing the whole batch.
Inputs: items (required).
create_app_store_qrA
Create a QR code that redirects to the correct app store based on the device. iPhones go to the App Store, Android devices go to Google Play, and other devices go to the fallback URL. Provide at least one store URL.
Inputs: ios_url, android_url, fallback_url, label, +10 more.
create_email_qrB
Create a QR code that opens a pre-filled email when scanned. The recipient, subject, body, CC, and BCC can all be pre-set.
Inputs: to (required), subject, body, cc, +12 more.
create_event_qrB
Create a QR code that adds a calendar event when scanned. Encodes a standard iCalendar VEVENT that calendar apps can import.
Inputs: summary (required), start (required), end (required), location, +12 more.
create_location_qrB
Create a QR code that opens a map location when scanned. Encodes geographic coordinates that map apps can parse.
Inputs: latitude (required), longitude (required), label, qr_label, +10 more.
create_phone_qrB
Create a QR code that initiates a phone call when scanned. The phone number is encoded directly in the QR code.
Inputs: phone_number (required), label, format, foreground_color, +8 more.
create_qr_codeA
Create a new managed QR code with optional custom styling. The QR code points to a short URL that redirects to your target URL. You can change the target URL later without regenerating the QR image. Supports custom colors, dot shapes, corner shapes, and logo embedding.
Inputs: target_url (required), label, format, foreground_color, +18 more.
create_sms_qrB
Create a QR code that opens a pre-filled SMS message when scanned. Set the phone number and optional message text.
Inputs: phone_number (required), message, label, format, +9 more.
create_social_qrA
Create a QR code that links to social media profiles. When scanned via the short URL, returns a JSON object with all platform links. Provide at least one platform link.
Inputs: facebook, instagram, twitter, linkedin, +15 more.
create_text_qrA
Create a QR code that contains plain text. When scanned, the text is displayed directly. Useful for messages, notes, or any freeform content.
Inputs: content (required), label, format, foreground_color, +8 more.
create_vcard_qrA
Create a QR code that encodes a contact card (vCard). When scanned by a phone camera, it prompts the user to save the contact. Supports all standard vCard fields and custom QR styling.
Inputs: first_name (required), last_name (required), organization, title, +16 more.
create_webhookA
Register a webhook endpoint to receive real-time notifications when QR codes are scanned. Returns an HMAC-SHA256 secret for verifying webhook signatures — store it securely, it is only shown once.
Inputs: url (required), events.
create_wifi_qrC
Create a QR code that encodes WiFi credentials. When scanned by a phone camera, it offers to auto-join the WiFi network. No internet connection needed to join — the credentials are encoded directly in the QR image.
Inputs: ssid (required), password, encryption, hidden, +11 more.
delete_qr_codeA
Permanently delete a QR code and all its scan analytics. The short URL will stop working immediately. This cannot be undone.
Inputs: short_id (required).
delete_webhookA
Delete a webhook endpoint and all its delivery logs. The endpoint will stop receiving events immediately.
Inputs: webhook_id (required).
get_conversionsA
Get conversion statistics for a QR code. Returns total conversions, total value, breakdowns by event name, daily trends, and recent events. Use this to measure QR code ROI and understand which codes drive the most value.
Inputs: short_id (required), period, event.
get_custom_domainA
Get your current custom domain configuration and DNS verification status. Returns the domain, whether DNS is active or pending, and setup instructions.
Inputs: no named parameters.
get_qr_analyticsA
Get enriched scan analytics for a QR code. Returns total scans, daily trends, device/browser/country/referer breakdowns with percentages, and recent scan events with parsed user-agent and geo data.
Inputs: short_id (required), period.
get_qr_codeA
Retrieve details of an existing QR code by its short ID. Returns the current target URL, metadata, and timestamps.
Inputs: short_id (required).
get_usageA
Get current usage and quota for your API key.
Inputs: no named parameters.
list_qr_codesA
List all managed QR codes with pagination. Returns short IDs, target URLs, labels, and timestamps. Use this to browse or search for existing QR codes.
Inputs: limit, offset.
list_webhooksA
List all registered webhook endpoints for your API key. The HMAC secret is not included for security.
Inputs: no named parameters.
manage_billingA
Open the Stripe billing portal to manage your subscription, update payment method, or cancel. Returns a portal URL — tell the user to open it in their browser. Only works if you have an active Pro subscription.
Inputs: no named parameters.
record_conversionA
Record a post-scan conversion event (purchase, signup, etc.) for a QR code you own. Use this to track ROI — e.g., when a user scans a QR code and then makes a purchase, record a 'purchase' conversion with the order value. For client-side tracking without code, use the tracking pixel: .
Inputs: short_id (required), event (required), value, metadata.
registerA
Register for an API key. Provide your email to get a key immediately.
Inputs: email (required), label.
set_custom_domainA
Set a custom domain for your QR code short URLs (Pro plan required). When set, all new QR codes will use https://your-domain.com/r/... instead of the default URL. You must configure DNS (CNAME) to point to the QR Agent server. Pass domain=null to remove the custom domain.
Inputs: domain (required).
set_redirect_rulesA
Set conditional redirect rules on a URL QR code. Rules are evaluated top-to-bottom; each rule has an array of conditions (AND logic) — all must match. First matching rule's URL is used. If no rule matches, the default target_url applies. Conditions: 'device' (mobile/tablet/desktop), 'os' (iOS/Android/Windows/macOS/Linux), 'country' (ISO alpha-2 like 'FR'), 'language' (ISO 639-1 like 'fr'), 'time_range' ({start:'09:00',end:'17:00',timezone:'Europe/Paris'}), 'ab_split' ({percentage:50}). Combine conditions in a single rule for AND logic (e.g. mobile + FR). Pass an empty array to remove all rules.
Inputs: short_id (required), rules (required).
set_utm_paramsA
Set UTM tracking parameters on a URL QR code. These parameters are automatically appended to the target URL on every scan redirect. Use this to track QR code scans in Google Analytics or other analytics tools. Set 'clear' to true to remove all UTM parameters.
Inputs: short_id (required), source, medium, campaign, +3 more.
update_app_store_qrA
Update the app store URLs of an App Store QR code. Partial updates merge with existing data.
Inputs: short_id (required), ios_url, android_url, fallback_url, +1 more.
update_qr_destinationA
Change where an existing QR code redirects to. This is the key 'dynamic link' feature: the QR image stays the same, but scanning it will now go to the new URL. Ideal for updating campaigns, fixing broken links, or A/B testing.
Inputs: short_id (required), target_url (required), label, expires_at, +3 more.
update_social_qrB
Update the social media links of a Social QR code. Partial updates merge with existing data.
Inputs: short_id (required), facebook, instagram, twitter, +6 more.
update_vcard_qrA
Update the contact details of a vCard QR code. Only works on QR codes created with type='vcard'. Partial updates merge with existing data. Note: updating vCard data changes the QR image content.
Inputs: short_id (required), first_name, last_name, organization, +7 more.
update_wifi_qrA
Update the WiFi credentials of a WiFi QR code. Only works on QR codes created with type='wifi'. Note: updating WiFi data changes the QR image content.
Inputs: short_id (required), ssid, password, encryption, +2 more.
upgrade_to_proA
Upgrade to the Pro plan ($19/month) for unlimited QR codes, scans, and webhooks. Returns a Stripe Checkout URL — tell the user to open it in their browser to complete payment. The upgrade takes effect automatically after payment.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 37 tools
Each tool has a clearly distinct purpose, from creating specific QR code types (email, event, location, etc.) to bulk operations, analytics, and account management. No two tools appear to do the same thing, and descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_qr_code, get_qr_analytics, update_qr_destination). There are no deviations or mixed conventions, making the set predictable and easy to navigate.
With 37 tools, the count is high but justified by the breadth of functionality: multiple QR types (10+), bulk operations, analytics, webhooks, billing, and customization. While slightly bloated, each tool serves a specific need in QR code management.
The tool surface covers the full lifecycle: create (single, bulk, specialized types), read (list, get details, analytics), update (destination, styling, dynamic rules), delete, plus extras like webhooks, billing, custom domains, and conversion tracking. No obvious gaps for a QR code service.
Maintenance
Related MCP Connectors
Generate QR codes for URLs, PIX, Wi-Fi, vCards, WhatsApp and more. For AI agents.
Create dynamic QR codes, change where they go and read scan stats from your AI assistant.
Branded QR codes for AI agents: static or dynamic, re-pointable after printing, with scan counts.
Generate branded, scan-validated QR codes (manual, AI, templates, Wi-Fi, vCard, geo).
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables generation of QR codes from text or URLs in multiple formats (DataURL, SVG, terminal display) with customizable options like error correction, colors, and size. Supports batch processing of multiple QR codes and integrates seamlessly with MCP-compatible clients.44MIT
- AlicenseAqualityFmaintenanceEnables AI-powered generation of styled QR codes with 10 design presets, supporting single or batch creation with custom logos and formats (SVG/PNG) directly from AI tools.45MIT
- AlicenseAqualityDmaintenanceGenerate styled QR codes, manage dynamic short links with click analytics, and publish micro-landing pages via AI agents.1971 npm1MIT
- AlicenseNot gradedqualityDmaintenanceQrVerloz lets AI agents create QR codes instantly — no account needed, active for 90 days, and claimable at any time to make them permanent. Retarget the destination URL whenever you need, without reprinting.3MIT