Skip to main content
Glama
QR for Agent

QR for Agent

by benjaminturc

QR Agent Core

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

Available Tools

37 tools
bulk_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

    A3.9/5.0

    Scored across 37 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      4
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Generate styled QR codes, manage dynamic short links with click analytics, and publish micro-landing pages via AI agents.
      19
      71 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      QrVerloz 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.
      3
      MIT