QR for Agent
QR Agent Core
API de QR-as-a-Service creada para agentes de IA. Crea, actualiza y rastrea códigos QR dinámicos mediante programación a través de la API REST o MCP (37 herramientas).
Los códigos QR apuntan a URLs cortas (/r/:shortId) que puedes redirigir en cualquier momento: la imagen del QR nunca cambia, pero al escanearla se dirige al nuevo destino. Multitenant por diseño, con análisis completo de escaneos.
API en vivo: api.qragentcore.com | Sitio: qrforagent.com | MCP: qr-for-agent
Características
Códigos QR dinámicos — cambia la URL de destino sin regenerar la imagen
11 tipos de QR — URL, vCard, WiFi, Email, SMS, Teléfono, Evento, Texto, Ubicación, Redes Sociales, App Store
Estilos personalizados — formas de puntos (cuadrado, redondeado, puntos, classy-rounded), estilos de esquina, colores, degradados, incrustación de logotipos, marcos con texto CTA
SVG y PNG — salida vectorial y de mapa de bits
Análisis enriquecido — tipo de dispositivo, navegador, SO, país, ciudad, referente, escaneos por día
Webhooks en tiempo real — cargas útiles firmadas con HMAC-SHA256 con registro de entrega
Rastreo UTM — añade automáticamente parámetros UTM a las URLs de redirección
Soporte GTM — página intermedia con fragmentos de Google Tag Manager
Redirecciones condicionales — enruta por dispositivo, SO, país, idioma, rango de tiempo o división A/B
Dominios personalizados — los usuarios Pro pueden marcar sus URLs cortas con su propio dominio (
qr.tumarca.com/r/abc123)Expiración y programación — expira automáticamente códigos QR o programa cambios de URL
Rastreo de conversiones — píxel de seguimiento + API para eventos post-escaneo (compras, registros) con análisis de ROI
Marcos y plantillas — marcos decorativos alrededor de los códigos QR (banner_top, banner_bottom, redondeado) con texto CTA
Operaciones masivas — crea, actualiza o elimina hasta 50 códigos QR por solicitud, o hasta 500 mediante carga de CSV (Pro)
Multitenant — cada clave de API solo ve sus propios datos
Servidor MCP —
qr-for-agentcon 37 herramientas para Claude Desktop, Cursor, etc.Cuotas basadas en planes — Gratis (10 QR, 1K escaneos/mes) y Pro ($19/mes, ilimitado)
Registro autoservicio —
POST /api/registercon correo electrónico, sin tarjeta de créditoIntegración con Stripe — checkout, portal de facturación, gestión de planes basada en webhooks
Documentación OpenAPI — Swagger UI en
/documentationDescubrible por IA —
/.well-known/ai-plugin.jsony/.well-known/mcp.jsonCódigo abierto — licencia MIT, autohospedable mediante Docker
Related MCP server: QR Code Generator MCP
Inicio rápido
git clone https://github.com/benswel/qr-agent-core.git
cd qr-agent-core
npm install
npm run devEn el primer inicio, se genera automáticamente una clave de API que se imprime en la consola.
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"}'Endpoints de la API
Gestión de códigos QR (requiere X-API-Key)
Método | Ruta | Descripción |
|
| Crea un código QR (11 tipos, estilo personalizado) |
|
| Lista todos los códigos QR (paginado) |
|
| Obtiene detalles del código QR |
|
| Actualiza URL de destino, etiqueta, UTM, GTM, reglas de redirección |
|
| Elimina el código QR y sus análisis |
|
| Descarga la imagen del QR (regenerada con el estilo guardado) |
|
| Crea hasta 50 códigos QR (todo o nada) |
|
| Actualiza hasta 50 códigos QR (éxito parcial) |
|
| Elimina hasta 50 códigos QR (éxito parcial) |
|
| Crea hasta 500 códigos QR desde CSV (solo Pro) |
Análisis (requiere X-API-Key)
Método | Ruta | Descripción |
|
| Estadísticas de escaneo con desglose de dispositivo, navegador, SO, país, ciudad + conversiones |
Conversiones (requiere X-API-Key)
Método | Ruta | Descripción |
|
| Registra un evento de conversión para un código QR de tu propiedad |
|
| Obtiene estadísticas de conversión (totales, por_evento, por_día, recientes) |
Webhooks (requiere X-API-Key)
Método | Ruta | Descripción |
|
| Registra un endpoint de webhook (devuelve secreto HMAC) |
|
| Lista todos los webhooks |
|
| Elimina un webhook |
Dominio personalizado (requiere X-API-Key, solo Pro)
Método | Ruta | Descripción |
|
| Obtiene el dominio personalizado actual y el estado de DNS |
|
| Establece un dominio personalizado |
|
| Elimina el dominio personalizado |
Cuenta (requiere X-API-Key)
Método | Ruta | Descripción |
|
| Uso actual y cuota |
|
| Crea una sesión de Stripe Checkout (actualizar a Pro) |
|
| Abre el portal de facturación de Stripe |
Público (sin autenticación)
Método | Ruta | Descripción |
|
| Registro de clave de API autoservicio (limitado por tasa) |
|
| Redirige a la URL de destino (registra escaneo) |
|
| Píxel de seguimiento de conversiones (devuelve GIF 1×1) |
|
| Sirve la imagen del QR (cacheable) |
|
| Comprobación de estado |
|
| Swagger UI |
|
| Manifiesto del plugin de IA |
|
| Manifiesto de descubrimiento MCP |
Administrador (requiere cabecera X-Admin-Secret)
Método | Ruta | Descripción |
|
| Lista todas las claves de API registradas |
|
| Métricas del panel |
Autenticación
Todos los endpoints /api/* requieren una cabecera X-API-Key.
Formato:
qr_+ cadena aleatoria de 32 caracteresGenerado automáticamente: en el primer inicio si no existen claves
Multitenant: cada clave solo ve sus propios códigos QR
Crear una clave:
npm run key:create "mi-etiqueta"Listar claves:
npm run key:list
Los endpoints públicos (/r/*, /i/*, /health, /documentation, /.well-known/*) no requieren autenticación.
Servidor MCP
Publicado como qr-for-agent en npm. 37 herramientas para que los agentes de IA gestionen códigos QR de forma nativa.
npx qr-for-agentClaude Desktop / Cursor
Añade a tu configuración de MCP (claude_desktop_config.json o .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"
}
}
}
}Herramientas disponibles (37)
Herramienta | Descripción |
| Crea un código QR de URL con estilo personalizado opcional |
| Obtiene detalles del código QR por ID corto |
| Cambia a dónde redirige un código QR |
| Lista todos los códigos QR con paginación |
| Elimina un código QR y sus análisis |
| Obtiene estadísticas de escaneo y desgloses |
| Crea hasta 50 códigos QR a la vez |
| Actualiza hasta 50 códigos QR a la vez |
| Elimina hasta 50 códigos QR a la vez |
| Crea un código QR de contacto vCard |
| Crea un código QR de credenciales WiFi |
| Crea un código QR de correo electrónico (mailto:) |
| Crea un código QR de SMS |
| Crea un código QR de llamada telefónica |
| Crea un código QR de evento de calendario |
| Crea un código QR de texto plano |
| Crea un código QR de geolocalización |
| Crea un código QR de enlaces a redes sociales |
| Crea un código QR de redirección inteligente a App Store |
| Actualiza un código QR vCard |
| Actualiza un código QR WiFi |
| Actualiza un código QR de redes sociales |
| Actualiza un código QR de App Store |
| Registra un endpoint de webhook |
| Lista todos los webhooks registrados |
| Elimina un webhook |
| Regístrate para obtener una clave de API |
| Obtiene el uso actual y la cuota |
| Crea una sesión de Stripe Checkout |
| Abre el portal de facturación de Stripe |
| Establece parámetros de seguimiento UTM en un código QR |
| Establece reglas de redirección condicional en un código QR |
| Establece o elimina un dominio personalizado (Pro) |
| Obtiene el dominio personalizado actual y el estado de DNS |
| Crea hasta 500 códigos QR desde datos CSV (Pro) |
| Registra un evento de conversión post-escaneo |
| Obtiene estadísticas de conversión para un código QR |
Configuración
Copia .env.example a .env y edita:
Variable | Predeterminado | Descripción |
|
| Puerto HTTP |
|
| Dirección de enlace |
|
| URL pública (usada en URLs cortas) |
|
| Ruta del archivo SQLite |
|
| Longitud de los IDs cortos generados |
| (ninguno) | Secreto para endpoints de administración (cabecera |
| (ninguno) | Clave secreta de la API de Stripe |
| (ninguno) | Secreto de firma de webhook de Stripe |
| (ninguno) | ID de precio de Stripe para el plan Pro |
Base de datos
SQLite con Drizzle ORM. Seis tablas:
api_keys— almacenamiento de claves con etiqueta, correo electrónico, plan (gratis/pro), IDs de Stripe, dominio personalizadoqr_codes— metadatos de QR, URLs de destino, tipo/datos_tipo, opciones de estilo, UTM, GTM, reglas de redirección, expiración/programaciónscan_events— seguimiento de escaneo: marca de tiempo, agente de usuario, referente, IP, dispositivo, navegador, SO, país, ciudadwebhooks— endpoints de webhook por clave de API, secreto HMAC, eventos suscritoswebhook_deliveries— registro de entrega: estado, código de respuesta, mensajes de errorconversion_events— seguimiento de conversiones: nombre del evento, valor, metadatos, referente, IP, marca de tiempo
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)Las migraciones se ejecutan automáticamente al iniciar el servidor.
Despliegue
Docker
docker compose up -dLa base de datos persiste en un volumen de Docker.
Railway
El proyecto incluye railway.toml y un Dockerfile multietapa. Conecta tu repositorio de GitHub a Railway: se construye y despliega automáticamente con comprobaciones de estado en /health.
Pruebas
195 pruebas de integración que cubren todos los endpoints, autenticación, aislamiento multitenant, tipos de QR, webhooks, operaciones masivas, dominios personalizados, marcos, conversiones, carga de CSV y análisis.
npm test # Run all tests
npm run test:watch # Watch modeScripts
Script | Descripción |
| Inicia el servidor de desarrollo con recarga automática |
| Compila TypeScript |
| Ejecuta el servidor de producción |
| Ejecuta la suite de pruebas |
| Pruebas en modo de vigilancia |
| Crea una clave de API |
| Lista las claves de API |
| Genera migración |
| Ejecuta migraciones |
| Abre Drizzle Studio |
Licencia
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