Servidor MCP de QR Branding

Habla con tu editor o con tu aplicación de escritorio de IA y haz que genere códigos QR a través del motor de QR Branding. El servidor MCP envuelve la API pública como un conjunto de herramientas que puede llamar cualquier cliente compatible con MCP. Puedes usarlo de dos formas:

• Servidor remoto en https://qr-branding.com/mcp: no hay nada que instalar, solo pegas una URL y tu clave de API en el cliente.
• Servidor local, el paquete npm @qr-branding/mcp-server (Node 20+), que tu cliente lanza por stdio.

Ambos exponen las mismas siete herramientas y se autentican con la misma clave de API de QR Branding. Código fuente: mcp-server/.

Qué incluye

Siete herramientas asociadas a la pasarela pública en https://qr-branding.com/api/v1/*:

qr_build_vcard admite estos campos: firstName (obligatorio), lastName, organization, phone, email y url. Todavía no se admiten la dirección postal, el cargo ni las notas. qr_build_geo solo acepta latitude y longitude (sin altitud).

Los formatos de mapa de bits (PNG, JPG, WEBP) y SVG llegan como bloques de contenido de imagen en línea, así que los clientes que muestran imágenes MCP enseñan el QR directamente en el chat. Los PDF no se pueden incrustar: el servidor local los escribe en un archivo temporal y devuelve la ruta; el servidor remoto los devuelve como un recurso application/pdf incrustado.

Requisitos previos

1. Una clave de API: inicia sesión en qr-branding.com, ve a Panel → Claves de API, pulsa Generar clave y copia el valor qrb_… en ese momento. No volverás a verlo, pero puedes emitir más.
2. Plan Studio: la API exige un pack Studio activo. Con cualquier otro plan, las llamadas a las herramientas fallan con studio_required y el error le llega al modelo con una sugerencia para mejorar el plan. Las generaciones con IA gastan además créditos de IA de Studio (out_of_api_credits cuando se agotan).
3. Node 20+, solo para el servidor local, en la máquina que aloja el proceso MCP (normalmente tu portátil). npx se encarga de la instalación.

Servidor remoto (Streamable HTTP)

El endpoint es https://qr-branding.com/mcp y usa el transporte Streamable HTTP de MCP (sin estado, respuestas JSON). Envía tu clave en cualquiera de estas cabeceras:

• Authorization: Bearer qrb_PASTE_YOUR_KEY (lo que configuran la mayoría de los clientes)
• X-API-Key: qrb_PASTE_YOUR_KEY (la misma cabecera que la API REST)

Una petición sin clave válida recibe 401 con una cabecera WWW-Authenticate: Bearer.

Claude Code (CLI)

claude mcp add --transport http qr-branding https://qr-branding.com/mcp \
  --header "Authorization: Bearer qrb_PASTE_YOUR_KEY"

Ejecuta /mcp en una sesión para comprobar que el servidor está conectado y pide cosas como "genera un QR para https://qr-branding.com con módulos en forma de hoja y color dorado"; Claude llamará a qr_generate.

Cursor

~/.cursor/mcp.json (o Settings → MCP):

{
  "mcpServers": {
    "qr-branding": {
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

VS Code (modo agente de GitHub Copilot)

.vscode/mcp.json en tu espacio de trabajo:

{
  "servers": {
    "qr-branding": {
      "type": "http",
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

Otros clientes

Cualquier cliente que admita Streamable HTTP con cabeceras personalizadas funciona con el mismo par url + headers. Un cliente que solo lance servidores stdio puede usar en su lugar el servidor local.

Conectores personalizados de claude.ai y Claude Desktop

Los conectores personalizados añadidos desde claude.ai (web y los ajustes de Conectores de Claude Desktop) se autentican con OAuth, que el servidor MCP de QR Branding todavía no admite: no pueden enviar una cabecera con la clave de API. Hasta que lo admita, usa el servidor local en Claude Desktop (más abajo) o Claude Code con el servidor remoto.

Servidor local (npm, stdio)

Tu cliente lanza npx @qr-branding/mcp-server y habla JSON-RPC por la entrada y la salida estándar del proceso. La clave va en la variable de entorno QR_BRANDING_API_KEY.

Claude Code (CLI)

claude mcp add qr-branding --env QR_BRANDING_API_KEY=qrb_PASTE_YOUR_KEY -- npx -y @qr-branding/mcp-server

Claude Desktop (macOS / Windows)

Abre el archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Cierra Claude Desktop por completo y vuelve a abrirlo. El servidor de QR Branding debería aparecer como disponible en el menú de herramientas junto al campo de mensaje.

Cursor

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Reinicia Cursor. Las herramientas quedan disponibles tanto para el agente del chat como para Composer.

ChatGPT Desktop

ChatGPT Desktop lee ~/.openai/chatgpt/mcp-config.json (la ruta puede variar según la versión; compruébalo en Settings → Beta features → Model Context Protocol):

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Continue (extensión de VS Code / JetBrains)

En tu configuración de Continue (~/.continue/config.json o .continue/config.json del espacio de trabajo), dentro de mcpServers:

"mcpServers": [
  {
    "name": "qr-branding",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
]

Zed

Abre ~/.config/zed/settings.json y añade en context_servers:

"context_servers": {
  "qr-branding": {
    "source": "custom",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
}

Variables de entorno (servidor local)

Comprueba que funciona

Servidor remoto: lista las herramientas con curl:

curl -s https://qr-branding.com/mcp \
  -H "Authorization: Bearer qrb_PASTE_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Servidor local: ejecuta la prueba de humo desde el código fuente:

cd mcp-server
npm install
QR_BRANDING_API_KEY=qrb_xxx npm run smoke
QR_BRANDING_API_KEY=qrb_xxx SMOKE_GENERATE=1 npm run smoke

La prueba de humo consulta /api/v1/qr/ping y /api/v1/qr/templates, imprime el número de plantillas y (con SMOKE_GENERATE=1) genera de extremo a extremo un QR de prueba muy pequeño.

Costes y límites

• Las llamadas de generación: la generación manual, las plantillas y las utilidades de contenido no gastan créditos; la generación con IA en nuestras claves (qr_generate_ai) gasta un crédito de IA de Studio. Las llamadas de listado y de metadatos de plantillas tampoco consumen créditos. Consulta Precios y créditos.
• Los límites de peticiones son los de la pasarela: consulta la visión general de la API. En el servidor remoto, cada llamada a una herramienta cuenta como una petición contra el límite por minuto y el tope diario de tu clave; el handshake y tools/list solo cuentan contra el límite por red.
• El coste del lado del asistente de IA depende de los precios de tu asistente (uso de Claude, suscripción a ChatGPT, etc.). El servidor MCP en sí es gratuito.

Privacidad y seguridad

• El servidor MCP reenvía a qr-branding.com tus prompts y las URL o textos que le pases. Sin telemetría de terceros ni SDK de analítica.
• La clave de API vive en la configuración de tu cliente; nunca aparece en las transcripciones del chat ni en el contexto del modelo. El servidor remoto solo la recibe por HTTPS y la comprueba contra un hash, igual que la API REST.
• Rota la clave cuando quieras en Panel → Claves de API; las claves antiguas se revocan al instante.

Solución de problemas

• "QR_BRANDING_API_KEY not set" (local): la variable de entorno no llegó al proceso npx lanzado. Comprueba que el JSON es válido y reinicia la aplicación anfitriona.
• 401 invalid_api_key / missing_api_key (remoto): la cabecera no llegó o la clave se revocó. Revisa la cabecera Authorization: Bearer qrb_… en la configuración del cliente.
• studio_required: tu cuenta no tiene un pack Studio activo (Starter y Pro solo incluyen el editor). Consigue Studio en precios.
• out_of_api_credits: has agotado los créditos de IA de Studio. Recarga en precios.
• La imagen no se muestra en línea: puede que tu cliente no gestione el contenido de imagen de MCP. Los mapas de bits y los SVG usan el tipo de contenido de imagen de la especificación; los PDF llegan como una ruta de archivo (local) o como un recurso incrustado (remoto).
• Errores de red / tiempos de espera: la pasarela está en https://qr-branding.com. Si tu red la bloquea, sobrescribe QR_BRANDING_API_BASE_URL (servidor local).

Próximamente

Estamos siguiendo estas mejoras para próximas versiones:

• OAuth en el servidor remoto, para poder añadirlo como conector personalizado en claude.ai y en otros clientes que lo exijan.
• Una herramienta qr_dynamic_create que cree QR dinámicos imprimibles (el redirector /q/{slug}) sin salir del chat.
• Manejadores de recursos para explorar las plantillas como recursos MCP (para que los clientes con selector de recursos puedan mostrarlas en su interfaz).

Abre incidencias o solicitudes de funciones en el repositorio. El código del paquete está en el mismo monorepo que el motor.