QR Agent Core

QR-as-a-Service API built for AI agents. Create, update, and track dynamic QR codes programmatically via REST API or MCP (37 tools).

QR codes point to short URLs (/r/:shortId) that you can retarget at any time — the QR image never changes, but scanning it goes to the new destination. Multi-tenant by design, with full scan analytics.

Live API: api.qragentcore.com  |  Site: qrforagent.com  |  MCP: qr-for-agent

Features

• Dynamic QR codes — change the destination URL without regenerating the image
• 11 QR types — URL, vCard, WiFi, Email, SMS, Phone, Event, Text, Location, Social, App Store
• Custom styling — dot shapes (square, rounded, dots, classy-rounded), corner styles, colors, gradients, logo embedding, frames with CTA text
• SVG & PNG — vector and bitmap output
• Enriched analytics — device type, browser, OS, country, city, referrer, scans-by-day
• Real-time webhooks — HMAC-SHA256 signed payloads with delivery logging
• UTM tracking — auto-append UTM parameters to redirect URLs
• GTM support — intermediate page with Google Tag Manager snippets
• Conditional redirects — route by device, OS, country, language, time range, or A/B split
• Custom domains — Pro users brand short URLs with their own domain (qr.yourbrand.com/r/abc123)
• Expiration & scheduling — auto-expire QR codes or schedule URL swaps
• Conversion tracking — tracking pixel + API for post-scan events (purchases, signups) with ROI analytics
• Frames & templates — decorative frames around QR codes (banner_top, banner_bottom, rounded) with CTA text
• Bulk operations — create, update, or delete up to 50 QR codes per request, or up to 500 via CSV upload (Pro)
• Multi-tenant — each API key sees only its own data
• MCP server — qr-for-agent with 37 tools for Claude Desktop, Cursor, etc.
• Plan-based quotas — Free (10 QR, 1K scans/month) and Pro ($19/month, unlimited)
• Self-service registration — POST /api/register with email, no credit card
• Stripe integration — checkout, billing portal, webhook-driven plan management
• OpenAPI docs — Swagger UI at /documentation
• AI-discoverable — /.well-known/ai-plugin.json and /.well-known/mcp.json
• Open source — MIT license, self-hostable via Docker

Quick Start

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

On first startup, an API key is auto-generated and printed to the console.

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 Endpoints

QR Code Management (X-API-Key required)

Analytics (X-API-Key required)

Conversions (X-API-Key required)

Webhooks (X-API-Key required)

Custom Domain (X-API-Key required, Pro only)

Account (X-API-Key required)

Public (no auth)

Admin (X-Admin-Secret header required)

Authentication

All /api/* endpoints require an X-API-Key header.

• Format: qr_ + 32-character random string
• Auto-generated: on first startup if no keys exist
• Multi-tenant: each key only sees its own QR codes
• Create a key: npm run key:create "my-label"
• List keys: npm run key:list

Public endpoints (/r/*, /i/*, /health, /documentation, /.well-known/*) don't require auth.

MCP Server

Published as qr-for-agent on npm. 37 tools for AI agents to manage QR codes natively.

npx qr-for-agent

Claude Desktop / Cursor

Add to your MCP config (claude_desktop_config.json or .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"
      }
    }
  }
}

Available Tools (37)

Configuration

Copy .env.example to .env and edit:

Database

SQLite with Drizzle ORM. Six tables:

• api_keys — key storage with label, email, plan (free/pro), Stripe IDs, custom domain
• qr_codes — QR metadata, target URLs, type/type_data, style options, UTM, GTM, redirect rules, expiration/scheduling
• scan_events — scan tracking: timestamp, user-agent, referer, IP, device, browser, OS, country, city
• webhooks — webhook endpoints per API key, HMAC secret, subscribed events
• webhook_deliveries — delivery log: status, response code, error messages
• conversion_events — conversion tracking: event name, value, metadata, referer, IP, timestamp

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)

Migrations run automatically on server startup.

Deployment

Docker

docker compose up -d

The database is persisted in a Docker volume.

Railway

The project includes railway.toml and a multi-stage Dockerfile. Connect your GitHub repo to Railway — it builds and deploys automatically with health checks on /health.

Tests

195 integration tests covering all endpoints, auth, multi-tenant isolation, QR types, webhooks, bulk operations, custom domains, frames, conversions, CSV upload, and analytics.

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

Scripts

License

MIT