QR Agent Core

Name: QR for Agent
Author: benswel

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

QR for Agent

QR Agent Core

Características

Inicio rápido

Endpoints de la API

Gestión de códigos QR (requiere `X-API-Key`)

Análisis (requiere `X-API-Key`)

Conversiones (requiere `X-API-Key`)

Webhooks (requiere `X-API-Key`)

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

Cuenta (requiere `X-API-Key`)

Público (sin autenticación)

Administrador (requiere cabecera `X-Admin-Secret`)

Autenticación

Servidor MCP

Claude Desktop / Cursor

Herramientas disponibles (37)

Configuración

Base de datos

Despliegue

Docker

Railway

Pruebas

Scripts

Licencia

Resources

Tools

Latest Blog Posts

MCP directory API

QR Agent Core

Características

Inicio rápido

Endpoints de la API

Gestión de códigos QR (requiere X-API-Key)

Análisis (requiere X-API-Key)

Conversiones (requiere X-API-Key)

Webhooks (requiere X-API-Key)

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

Cuenta (requiere X-API-Key)

Público (sin autenticación)

Administrador (requiere cabecera X-Admin-Secret)

Autenticación

Servidor MCP

Claude Desktop / Cursor

Herramientas disponibles (37)

Configuración

Base de datos

Despliegue

Docker

Railway

Pruebas

Scripts

Licencia

Resources

Tools

Latest Blog Posts

MCP directory API

Gestión de códigos QR (requiere `X-API-Key`)

Análisis (requiere `X-API-Key`)

Conversiones (requiere `X-API-Key`)

Webhooks (requiere `X-API-Key`)

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

Cuenta (requiere `X-API-Key`)

Administrador (requiere cabecera `X-Admin-Secret`)