qr-for-agent

qr-for-agent

MCP server for dynamic QR codes — create, style, track, and update QR codes from any AI agent.

37 tools for Claude Desktop, Cursor, Windsurf, VS Code, and any MCP-compatible client.

Website: qrforagent.com  |  Docs: qrforagent.com/docs  |  GitHub: benswel/qr-for-agent-api

Why QR for Agent?

• Dynamic — change the destination URL anytime, the QR image stays the same
• 11 QR types — URL, vCard, WiFi, Email, SMS, Phone, Event, Text, Location, Social, App Store
• Custom styling — dot shapes, corner styles, colors, gradients, logos, frames with CTA text
• Analytics — scan tracking with device, browser, OS, country, city breakdowns
• Webhooks — real-time scan notifications with HMAC-SHA256 signatures
• Conversion tracking — tracking pixel + API for post-scan events
• Free tier — 10 QR codes, 1K scans/month, no credit card required

Quick Start

npx qr-for-agent --api-key YOUR_KEY

No API key yet? Get one free at qrforagent.com/get-started or ask the agent to register with your email.

Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "qr_your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add qr-for-agent -- npx -y qr-for-agent

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "qr_your-api-key"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "qr_your-api-key"
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Description
API_KEY	Yes	—	Your QR for Agent API key
BASE_URL	No	https://api.qrforagent.com	Custom instance URL (self-hosting)

Tools (37)

QR Code Management (9)

Tool	Description
create_qr_code	Create a URL QR code with custom styling (colors, dot/corner shapes, gradients, logo, frames)
get_qr_code	Get QR code details by short ID
update_qr_destination	Change where a QR code redirects — the image stays the same
list_qr_codes	List all QR codes with pagination
delete_qr_code	Delete a QR code and its analytics
get_qr_analytics	Get scan stats with device, browser, OS, country, city breakdowns
bulk_create_qr_codes	Create up to 50 QR codes at once
bulk_update_qr_codes	Update up to 50 QR codes at once
bulk_delete_qr_codes	Delete up to 50 QR codes at once

QR Types (14)

Create and update specialized QR code types with structured data:

Tool	Description
create_vcard_qr	Contact card (name, phone, email, address)
create_wifi_qr	WiFi credentials (SSID, password, encryption)
create_email_qr	Pre-filled email (mailto: link)
create_sms_qr	Pre-filled SMS message
create_phone_qr	Phone call (tel: link)
create_event_qr	Calendar event (iCalendar)
create_text_qr	Plain text
create_location_qr	GPS coordinates (geo: URI)
create_social_qr	Multi-platform social media links
create_app_store_qr	Smart iOS/Android app store redirect
update_vcard_qr	Update a vCard QR code
update_wifi_qr	Update a WiFi QR code
update_social_qr	Update a social media QR code
update_app_store_qr	Update an app store QR code

Webhooks (3)

Tool	Description
create_webhook	Register an endpoint for real-time scan/conversion notifications (HMAC-signed)
list_webhooks	List all registered webhook endpoints
delete_webhook	Remove a webhook endpoint

Redirect & Tracking (4)

Tool	Description
set_utm_params	Set UTM tracking parameters (source, medium, campaign) on a QR code
set_redirect_rules	Set conditional redirects (by device, OS, country, language, time, A/B split)
record_conversion	Record a post-scan conversion event (purchase, signup, etc.)
get_conversions	Get conversion stats for a QR code (totals, by event, by day)

Custom Domains (2)

Tool	Description
set_custom_domain	Set or remove a branded short URL domain (Pro only)
get_custom_domain	Get current custom domain and DNS verification status

CSV Bulk (1)

Tool	Description
bulk_create_from_csv	Create up to 500 QR codes from CSV data (Pro only)

Account & Billing (4)

Tool	Description
register	Register for a free API key with your email
get_usage	Get current usage and quota for your plan
upgrade_to_pro	Upgrade to Pro ($19/month) — returns a Stripe Checkout URL
manage_billing	Open Stripe billing portal to manage subscription

Custom QR Styling

The create_qr_code tool (and all create_*_qr tools) supports:

• Colors: foreground_color, background_color (hex)
• Gradients: linear or radial gradients for dots and finder patterns
• Dot styles: square, rounded, dots, classy-rounded
• Corner styles: square, extra-rounded, dot
• Logo: logo_url (URL or data:base64), logo_size (0.15–0.3)
• Frames: banner_top, banner_bottom, rounded with custom CTA text
• Size: width (200–2000px), margin (0–10), error_correction (L/M/Q/H)

Plans

	Free	Pro ($19/month)
QR codes	10	Unlimited
Scans/month	1,000	Unlimited
Webhooks	1	Unlimited
Custom domains	—	✓
CSV bulk upload	—	✓ (500/batch)

How It Works

This MCP server is a thin HTTP client (~5 KB). It forwards tool calls to the QR for Agent API, which handles QR generation, storage, redirects, and analytics. The QR codes are "dynamic" — you can change the destination URL at any time without regenerating the QR image.

Self-Hosting

QR for Agent is open source (MIT). You can self-host:

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

Then point the MCP server to your instance:

BASE_URL=http://localhost:3100 API_KEY=your-key npx qr-for-agent

License

MIT