Skip to main content
Glama
QR for Agent

QR for Agent

by benjaminturc

QR Agent Core

benswel/qr-agent-core MCP server

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-agent con 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/register con correo electrónico, sin tarjeta de crédito

  • Integración con Stripe — checkout, portal de facturación, gestión de planes basada en webhooks

  • Documentación OpenAPI — Swagger UI en /documentation

  • Descubrible por IA — /.well-known/ai-plugin.json y /.well-known/mcp.json

  • Có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 dev

En 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

POST

/api/qr

Crea un código QR (11 tipos, estilo personalizado)

GET

/api/qr

Lista todos los códigos QR (paginado)

GET

/api/qr/:shortId

Obtiene detalles del código QR

PATCH

/api/qr/:shortId

Actualiza URL de destino, etiqueta, UTM, GTM, reglas de redirección

DELETE

/api/qr/:shortId

Elimina el código QR y sus análisis

GET

/api/qr/:shortId/image

Descarga la imagen del QR (regenerada con el estilo guardado)

POST

/api/qr/bulk

Crea hasta 50 códigos QR (todo o nada)

PATCH

/api/qr/bulk

Actualiza hasta 50 códigos QR (éxito parcial)

DELETE

/api/qr/bulk

Elimina hasta 50 códigos QR (éxito parcial)

POST

/api/qr/bulk/csv

Crea hasta 500 códigos QR desde CSV (solo Pro)

Análisis (requiere X-API-Key)

Método

Ruta

Descripción

GET

/api/analytics/:shortId

Estadísticas de escaneo con desglose de dispositivo, navegador, SO, país, ciudad + conversiones

Conversiones (requiere X-API-Key)

Método

Ruta

Descripción

POST

/api/conversions

Registra un evento de conversión para un código QR de tu propiedad

GET

/api/conversions/:shortId

Obtiene estadísticas de conversión (totales, por_evento, por_día, recientes)

Webhooks (requiere X-API-Key)

Método

Ruta

Descripción

POST

/api/webhooks

Registra un endpoint de webhook (devuelve secreto HMAC)

GET

/api/webhooks

Lista todos los webhooks

DELETE

/api/webhooks/:id

Elimina un webhook

Dominio personalizado (requiere X-API-Key, solo Pro)

Método

Ruta

Descripción

GET

/api/domain

Obtiene el dominio personalizado actual y el estado de DNS

PUT

/api/domain

Establece un dominio personalizado

DELETE

/api/domain

Elimina el dominio personalizado

Cuenta (requiere X-API-Key)

Método

Ruta

Descripción

GET

/api/usage

Uso actual y cuota

POST

/api/stripe/checkout

Crea una sesión de Stripe Checkout (actualizar a Pro)

POST

/api/stripe/portal

Abre el portal de facturación de Stripe

Público (sin autenticación)

Método

Ruta

Descripción

POST

/api/register

Registro de clave de API autoservicio (limitado por tasa)

GET

/r/:shortId

Redirige a la URL de destino (registra escaneo)

GET

/t/:shortId

Píxel de seguimiento de conversiones (devuelve GIF 1×1)

GET

/i/:shortId

Sirve la imagen del QR (cacheable)

GET

/health

Comprobación de estado

GET

/documentation

Swagger UI

GET

/.well-known/ai-plugin.json

Manifiesto del plugin de IA

GET

/.well-known/mcp.json

Manifiesto de descubrimiento MCP

Administrador (requiere cabecera X-Admin-Secret)

Método

Ruta

Descripción

GET

/api/admin/keys

Lista todas las claves de API registradas

GET

/api/admin/stats

Métricas del panel

Autenticación

Todos los endpoints /api/* requieren una cabecera X-API-Key.

  • Formato: qr_ + cadena aleatoria de 32 caracteres

  • Generado 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-agent

Claude 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

create_qr_code

Crea un código QR de URL con estilo personalizado opcional

get_qr_code

Obtiene detalles del código QR por ID corto

update_qr_destination

Cambia a dónde redirige un código QR

list_qr_codes

Lista todos los códigos QR con paginación

delete_qr_code

Elimina un código QR y sus análisis

get_qr_analytics

Obtiene estadísticas de escaneo y desgloses

bulk_create_qr_codes

Crea hasta 50 códigos QR a la vez

bulk_update_qr_codes

Actualiza hasta 50 códigos QR a la vez

bulk_delete_qr_codes

Elimina hasta 50 códigos QR a la vez

create_vcard_qr

Crea un código QR de contacto vCard

create_wifi_qr

Crea un código QR de credenciales WiFi

create_email_qr

Crea un código QR de correo electrónico (mailto:)

create_sms_qr

Crea un código QR de SMS

create_phone_qr

Crea un código QR de llamada telefónica

create_event_qr

Crea un código QR de evento de calendario

create_text_qr

Crea un código QR de texto plano

create_location_qr

Crea un código QR de geolocalización

create_social_qr

Crea un código QR de enlaces a redes sociales

create_app_store_qr

Crea un código QR de redirección inteligente a App Store

update_vcard_qr

Actualiza un código QR vCard

update_wifi_qr

Actualiza un código QR WiFi

update_social_qr

Actualiza un código QR de redes sociales

update_app_store_qr

Actualiza un código QR de App Store

create_webhook

Registra un endpoint de webhook

list_webhooks

Lista todos los webhooks registrados

delete_webhook

Elimina un webhook

register

Regístrate para obtener una clave de API

get_usage

Obtiene el uso actual y la cuota

upgrade_to_pro

Crea una sesión de Stripe Checkout

manage_billing

Abre el portal de facturación de Stripe

set_utm_params

Establece parámetros de seguimiento UTM en un código QR

set_redirect_rules

Establece reglas de redirección condicional en un código QR

set_custom_domain

Establece o elimina un dominio personalizado (Pro)

get_custom_domain

Obtiene el dominio personalizado actual y el estado de DNS

bulk_create_from_csv

Crea hasta 500 códigos QR desde datos CSV (Pro)

record_conversion

Registra un evento de conversión post-escaneo

get_conversions

Obtiene estadísticas de conversión para un código QR

Configuración

Copia .env.example a .env y edita:

Variable

Predeterminado

Descripción

PORT

3100

Puerto HTTP

HOST

0.0.0.0

Dirección de enlace

BASE_URL

http://localhost:3100

URL pública (usada en URLs cortas)

DATABASE_URL

./data/qr-agent.db

Ruta del archivo SQLite

SHORT_ID_LENGTH

8

Longitud de los IDs cortos generados

ADMIN_SECRET

(ninguno)

Secreto para endpoints de administración (cabecera X-Admin-Secret)

STRIPE_SECRET_KEY

(ninguno)

Clave secreta de la API de Stripe

STRIPE_WEBHOOK_SECRET

(ninguno)

Secreto de firma de webhook de Stripe

STRIPE_PRICE_ID

(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 personalizado

  • qr_codes — metadatos de QR, URLs de destino, tipo/datos_tipo, opciones de estilo, UTM, GTM, reglas de redirección, expiración/programación

  • scan_events — seguimiento de escaneo: marca de tiempo, agente de usuario, referente, IP, dispositivo, navegador, SO, país, ciudad

  • webhooks — endpoints de webhook por clave de API, secreto HMAC, eventos suscritos

  • webhook_deliveries — registro de entrega: estado, código de respuesta, mensajes de error

  • conversion_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 -d

La 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 mode

Scripts

Script

Descripción

npm run dev

Inicia el servidor de desarrollo con recarga automática

npm run build

Compila TypeScript

npm start

Ejecuta el servidor de producción

npm test

Ejecuta la suite de pruebas

npm run test:watch

Pruebas en modo de vigilancia

npm run key:create

Crea una clave de API

npm run key:list

Lista las claves de API

npm run db:generate

Genera migración

npm run db:migrate

Ejecuta migraciones

npm run db:studio

Abre Drizzle Studio

Licencia

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