{
  "markdown": "# QR for Agent\n\n[![benswel/qr-for-agent-api MCP server](https://glama.ai/mcp/servers/benswel/qr-for-agent-api/badges/score.svg)](https://glama.ai/mcp/servers/benswel/qr-for-agent-api)\n\nQR-as-a-Service API built for AI agents. Create, update, and track dynamic QR codes programmatically via REST API or MCP (37 tools).\n\nQR 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.\n\n**Live API:** [api.qrforagent.com](https://api.qrforagent.com)  |  **Site:** [qrforagent.com](https://qrforagent.com)  |  **MCP:** [`qr-for-agent`](https://www.npmjs.com/package/qr-for-agent)\n\n## Features\n\n- **Dynamic QR codes** — change the destination URL without regenerating the image\n- **11 QR types** — URL, vCard, WiFi, Email, SMS, Phone, Event, Text, Location, Social, App Store\n- **Custom styling** — dot shapes (square, rounded, dots, classy-rounded), corner styles, colors, gradients, logo embedding, frames with CTA text\n- **SVG & PNG** — vector and bitmap output\n- **Enriched analytics** — device type, browser, OS, country, city, referrer, scans-by-day\n- **Real-time webhooks** — HMAC-SHA256 signed payloads with delivery logging\n- **UTM tracking** — auto-append UTM parameters to redirect URLs\n- **GTM support** — intermediate page with Google Tag Manager snippets\n- **Conditional redirects** — route by device, OS, country, language, time range, or A/B split\n- **Custom domains** — Pro users brand short URLs with their own domain (`qr.yourbrand.com/r/abc123`)\n- **Expiration & scheduling** — auto-expire QR codes or schedule URL swaps\n- **Conversion tracking** — tracking pixel + API for post-scan events (purchases, signups) with ROI analytics\n- **Frames & templates** — decorative frames around QR codes (banner_top, banner_bottom, rounded) with CTA text\n- **Bulk operations** — create, update, or delete up to 50 QR codes per request, or up to 500 via CSV upload (Pro)\n- **Multi-tenant** — each API key sees only its own data\n- **MCP server** — [`qr-for-agent`](https://www.npmjs.com/package/qr-for-agent) with 37 tools for Claude Desktop, Cursor, etc.\n- **Plan-based quotas** — Free (10 QR, 1K scans/month) and Pro ($19/month, unlimited)\n- **Self-service registration** — `POST /api/register` with email, no credit card\n- **Stripe integration** — checkout, billing portal, webhook-driven plan management\n- **OpenAPI docs** — Swagger UI at `/documentation`\n- **AI-discoverable** — `/.well-known/ai-plugin.json` and `/.well-known/mcp.json`\n- **Open source** — MIT license, self-hostable via Docker\n\n## Quick Start\n\n```bash\ngit clone https://github.com/benswel/qr-for-agent-api.git\ncd qr-for-agent-api\nnpm install\nnpm run dev\n```\n\nOn first startup, an API key is auto-generated and printed to the console.\n\n```bash\ncurl -X POST http://localhost:3100/api/qr \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: qr_YOUR_KEY_HERE\" \\\n  -d '{\"target_url\": \"https://example.com\", \"label\": \"My first QR\"}'\n```\n\n## API Endpoints\n\n### QR Code Management (`X-API-Key` required)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/qr` | Create a QR code (11 types, custom styling) |\n| `GET` | `/api/qr` | List all QR codes (paginated) |\n| `GET` | `/api/qr/:shortId` | Get QR code details |\n| `PATCH` | `/api/qr/:shortId` | Update target URL, label, UTM, GTM, redirect rules |\n| `DELETE` | `/api/qr/:shortId` | Delete QR code and its analytics |\n| `GET` | `/api/qr/:shortId/image` | Download QR image (regenerated with stored style) |\n| `POST` | `/api/qr/bulk` | Create up to 50 QR codes (all-or-nothing) |\n| `PATCH` | `/api/qr/bulk` | Update up to 50 QR codes (partial success) |\n| `DELETE` | `/api/qr/bulk` | Delete up to 50 QR codes (partial success) |\n| `POST` | `/api/qr/bulk/csv` | Create up to 500 QR codes from CSV (Pro only) |\n\n### Analytics (`X-API-Key` required)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/analytics/:shortId` | Scan stats with device, browser, OS, country, city breakdowns + conversions |\n\n### Conversions (`X-API-Key` required)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/conversions` | Record a conversion event for a QR code you own |\n| `GET` | `/api/conversions/:shortId` | Get conversion stats (totals, by_event, by_day, recent) |\n\n### Webhooks (`X-API-Key` required)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/webhooks` | Register webhook endpoint (returns HMAC secret) |\n| `GET` | `/api/webhooks` | List all webhooks |\n| `DELETE` | `/api/webhooks/:id` | Delete a webhook |\n\n### Custom Domain (`X-API-Key` required, Pro only)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/domain` | Get current custom domain and DNS status |\n| `PUT` | `/api/domain` | Set custom domain |\n| `DELETE` | `/api/domain` | Remove custom domain |\n\n### Account (`X-API-Key` required)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/usage` | Current usage and quota |\n| `POST` | `/api/stripe/checkout` | Create Stripe Checkout session (upgrade to Pro) |\n| `POST` | `/api/stripe/portal` | Open Stripe billing portal |\n\n### Public (no auth)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/register` | Self-service API key registration (rate-limited) |\n| `GET` | `/r/:shortId` | Redirect to target URL (records scan) |\n| `GET` | `/t/:shortId` | Conversion tracking pixel (returns 1×1 GIF) |\n| `GET` | `/i/:shortId` | Serve QR image (cacheable) |\n| `GET` | `/health` | Health check |\n| `GET` | `/documentation` | Swagger UI |\n| `GET` | `/.well-known/ai-plugin.json` | AI plugin manifest |\n| `GET` | `/.well-known/mcp.json` | MCP discovery manifest |\n\n### Admin (`X-Admin-Secret` header required)\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/api/admin/keys` | List all registered API keys |\n| `GET` | `/api/admin/stats` | Dashboard metrics |\n\n## Authentication\n\nAll `/api/*` endpoints require an `X-API-Key` header.\n\n- **Format**: `qr_` + 32-character random string\n- **Auto-generated**: on first startup if no keys exist\n- **Multi-tenant**: each key only sees its own QR codes\n- **Create a key**: `npm run key:create \"my-label\"`\n- **List keys**: `npm run key:list`\n\nPublic endpoints (`/r/*`, `/i/*`, `/health`, `/documentation`, `/.well-known/*`) don't require auth.\n\n## MCP Server\n\nPublished as [`qr-for-agent`](https://www.npmjs.com/package/qr-for-agent) on npm. 37 tools for AI agents to manage QR codes natively.\n\n```bash\nnpx qr-for-agent\n```\n\n### Claude Desktop / Cursor\n\nAdd to your MCP config (`claude_desktop_config.json` or `.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"qr-for-agent\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"qr-for-agent\"],\n      \"env\": {\n        \"API_KEY\": \"your-api-key\",\n        \"BASE_URL\": \"https://api.qrforagent.com\"\n      }\n    }\n  }\n}\n```\n\n### Available Tools (37)\n\n| Tool | Description |\n|------|-------------|\n| `create_qr_code` | Create a URL QR code with optional custom styling |\n| `get_qr_code` | Get QR code details by short ID |\n| `update_qr_destination` | Change where a QR code redirects |\n| `list_qr_codes` | List all QR codes with pagination |\n| `delete_qr_code` | Delete a QR code and its analytics |\n| `get_qr_analytics` | Get scan stats and breakdowns |\n| `bulk_create_qr_codes` | Create up to 50 QR codes at once |\n| `bulk_update_qr_codes` | Update up to 50 QR codes at once |\n| `bulk_delete_qr_codes` | Delete up to 50 QR codes at once |\n| `create_vcard_qr` | Create a vCard contact QR code |\n| `create_wifi_qr` | Create a WiFi credentials QR code |\n| `create_email_qr` | Create an email (mailto:) QR code |\n| `create_sms_qr` | Create an SMS QR code |\n| `create_phone_qr` | Create a phone call QR code |\n| `create_event_qr` | Create a calendar event QR code |\n| `create_text_qr` | Create a plain text QR code |\n| `create_location_qr` | Create a geo-location QR code |\n| `create_social_qr` | Create a social media links QR code |\n| `create_app_store_qr` | Create a smart app store redirect QR code |\n| `update_vcard_qr` | Update a vCard QR code |\n| `update_wifi_qr` | Update a WiFi QR code |\n| `update_social_qr` | Update a social media QR code |\n| `update_app_store_qr` | Update an app store QR code |\n| `create_webhook` | Register a webhook endpoint |\n| `list_webhooks` | List all registered webhooks |\n| `delete_webhook` | Delete a webhook |\n| `register` | Register for an API key |\n| `get_usage` | Get current usage and quota |\n| `upgrade_to_pro` | Create a Stripe Checkout session |\n| `manage_billing` | Open Stripe billing portal |\n| `set_utm_params` | Set UTM tracking parameters on a QR code |\n| `set_redirect_rules` | Set conditional redirect rules on a QR code |\n| `set_custom_domain` | Set or remove custom domain (Pro) |\n| `get_custom_domain` | Get current custom domain and DNS status |\n| `bulk_create_from_csv` | Create up to 500 QR codes from CSV data (Pro) |\n| `record_conversion` | Record a post-scan conversion event |\n| `get_conversions` | Get conversion stats for a QR code |\n\n## Configuration\n\nCopy `.env.example` to `.env` and edit:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `3100` | HTTP port |\n| `HOST` | `0.0.0.0` | Bind address |\n| `BASE_URL` | `http://localhost:3100` | Public URL (used in short URLs) |\n| `DATABASE_URL` | `./data/qr-agent.db` | SQLite file path |\n| `SHORT_ID_LENGTH` | `8` | Length of generated short IDs |\n| `ADMIN_SECRET` | *(none)* | Secret for admin endpoints (`X-Admin-Secret` header) |\n| `STRIPE_SECRET_KEY` | *(none)* | Stripe API secret key |\n| `STRIPE_WEBHOOK_SECRET` | *(none)* | Stripe webhook signing secret |\n| `STRIPE_PRICE_ID` | *(none)* | Stripe Price ID for Pro plan |\n\n## Database\n\nSQLite with [Drizzle ORM](https://orm.drizzle.team/). Six tables:\n\n- **`api_keys`** — key storage with label, email, plan (free/pro), Stripe IDs, custom domain\n- **`qr_codes`** — QR metadata, target URLs, type/type_data, style options, UTM, GTM, redirect rules, expiration/scheduling\n- **`scan_events`** — scan tracking: timestamp, user-agent, referer, IP, device, browser, OS, country, city\n- **`webhooks`** — webhook endpoints per API key, HMAC secret, subscribed events\n- **`webhook_deliveries`** — delivery log: status, response code, error messages\n- **`conversion_events`** — conversion tracking: event name, value, metadata, referer, IP, timestamp\n\n```bash\nnpm run db:generate   # Generate migration from schema changes\nnpm run db:migrate    # Apply pending migrations\nnpm run db:studio     # Open Drizzle Studio (web UI)\n```\n\nMigrations run automatically on server startup.\n\n## Deployment\n\n### Docker\n\n```bash\ndocker compose up -d\n```\n\nThe database is persisted in a Docker volume.\n\n### Railway\n\nThe 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`.\n\n## Tests\n\n195 integration tests covering all endpoints, auth, multi-tenant isolation, QR types, webhooks, bulk operations, custom domains, frames, conversions, CSV upload, and analytics.\n\n```bash\nnpm test           # Run all tests\nnpm run test:watch # Watch mode\n```\n\n## Scripts\n\n| Script | Description |\n|--------|-------------|\n| `npm run dev` | Start dev server with auto-reload |\n| `npm run build` | Compile TypeScript |\n| `npm start` | Run production server |\n| `npm test` | Run test suite |\n| `npm run test:watch` | Tests in watch mode |\n| `npm run key:create` | Create API key |\n| `npm run key:list` | List API keys |\n| `npm run db:generate` | Generate migration |\n| `npm run db:migrate` | Run migrations |\n| `npm run db:studio` | Open Drizzle Studio |\n\n## License\n\nMIT\n",
  "bytes": 11852,
  "sha": "c761ced606bd8aee49842beb553f3c562e3dbcf1188402a69f4942c3e767515b",
  "repo_slug": "benswel/qr-for-agent-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_benswel_qr_for_agent_c1b6d32c/readme"
}