Issuebage MCP Server
oficialplataforma de emisión de insignias digitales
¿Qué puedes hacer con Issuebage MCP?
- Valida tu clave de API — Pide a tu asistente que compruebe que tus credenciales de IssueBadge funcionan usando
validate_key. - Enumera las plantillas de insignias — Recupera tus plantillas de insignias disponibles para que puedas elegir la correcta antes de emitir.
- Emite un certificado — Envía un certificado a un destinatario por nombre y correo electrónico, devolviendo una URL de verificación pública.
- Inspecciona los códigos QR — Enumera los códigos QR dinámicos, obtén uno con su imagen PNG o revisa su historial de escaneos.
- Elimina un código QR — Elimina un código QR dinámico existente por su código.
Documentación
Servidor MCP de IssueBadge
Emite certificados e insignias verificables desde cualquier agente de IA. Este servidor de Model Context Protocol permite a Cursor, Claude, VS Code y otros clientes MCP listar tus plantillas de insignias de IssueBadge y enviar un certificado a un destinatario por nombre y correo electrónico.
Dos formas de ejecutarlo:
| Remoto (recomendado) | Local (stdio) | |
|---|---|---|
| Endpoint | https://issuebadge-mcp.issuebadge.workers.dev/mcp | npx issuebadge-mcp-server |
| Autenticación | cabecera Authorization: Bearer <API key> | variable de entorno ISSUEBADGE_API_KEY |
| Herramientas | validate_key, get_all_badges, issue_badge, list_qr_codes, get_qr_code, get_qr_code_scans, delete_qr_code | las mismas + create_badge |
| Almacenamiento | ninguno, sin estado | ninguno |
Necesitas una clave de API de IssueBadge: app.issuebadge.com → Developer → API key (https://app.issuebadge.com/developer/index).
Instalación
Cursor
Instala IssueBadge desde el Cursor Marketplace y pega tu clave de API cuando se te solicite. O añádelo manualmente en Settings → MCP:
{
"mcpServers": {
"issuebadge": {
"type": "streamable-http",
"url": "https://issuebadge-mcp.issuebadge.workers.dev/mcp",
"headers": { "Authorization": "Bearer YOUR_ISSUEBADGE_API_KEY" }
}
}
}
Claude Code
claude mcp add --transport http issuebadge https://issuebadge-mcp.issuebadge.workers.dev/mcp \
--header "Authorization: Bearer YOUR_ISSUEBADGE_API_KEY"
Este repositorio también es un plugin de Claude Code (.claude-plugin/plugin.json) e incluye una skill issuebadge que enseña al agente el flujo de trabajo listar → confirmar → emitir. El archivo .mcp.json del plugin lee la clave de la variable de entorno ISSUEBADGE_API_KEY, así que expórtala antes de iniciar Claude Code.
Claude Desktop / cualquier cliente stdio
{
"mcpServers": {
"issuebadge": {
"command": "npx",
"args": ["-y", "issuebadge-mcp-server"],
"env": { "ISSUEBADGE_API_KEY": "YOUR_ISSUEBADGE_API_KEY" }
}
}
}
VS Code (modo agente de Copilot)
.vscode/mcp.json:
{
"servers": {
"issuebadge": {
"type": "http",
"url": "https://issuebadge-mcp.issuebadge.workers.dev/mcp",
"headers": { "Authorization": "Bearer YOUR_ISSUEBADGE_API_KEY" }
}
}
}
Herramientas
| Herramienta | Entrada | Devuelve |
|---|---|---|
validate_key | – | { valid, message } |
get_all_badges | limit? | { badges: [{ id, name, description?, created_at? }] } |
issue_badge | badge_id, name, email?, phone?, idempotency_key?, metadata? | { issue_id, certificate_url, idempotency_key } |
create_badge (solo stdio) | name, description, issuing_organization_name, idempotency_key, badge_logo_path opcional, custom_fields, … | Respuesta de la API de IssueBadge |
issue_badge envía el certificado por correo electrónico al destinatario y devuelve una URL de verificación pública. Cada llamada con una nueva idempotency_key emite un nuevo certificado (se genera uno como mcp-<uuid> si lo omites). La API rechaza una clave reutilizada, así que tras una llamada fallida comprueba si el certificado se emitió antes de volver a llamar con una nueva clave.
Ejemplo de prompt una vez instalado: "Emite el certificado Course Completion a Jane Doe, jane@example.com."
Códigos QR dinámicos
| Herramienta | Entrada | Devuelve |
|---|---|---|
list_qr_codes | type?, limit? | { qr_codes: [...], total } |
get_qr_code | code | el código QR + bloque de imagen PNG |
get_qr_code_scans | code, limit? | { code, scan_count, scans: [{ scanned_at, referer }], total } |
delete_qr_code | code | { deleted: true, code } |
Tipos: url, vcard, paypal, wifi, email, phone, sms, maps, event, facebook, twitter, youtube, text, mecard. Los códigos se crean y se redirigen en el panel de IssueBadge; la imagen codifica una redirección de IssueBadge (scan_url), de modo que un código impreso sigue funcionando cuando cambia su destino.
Ejemplo de prompt: "Crea un código QR llamado Menu que abra https://example.com/menu y muéstramelo."
ChatGPT y OAuth
El servidor remoto también habla OAuth 2.1 para hosts que no pueden enviar una clave de API (aplicaciones de ChatGPT, conectores de Claude): una
solicitud sin bearer recibe 401 + WWW-Authenticate: Bearer resource_metadata=…, /.well-known/oauth-protected-resource
apunta a https://app.issuebadge.com (PKCE S256, registro dinámico de clientes), y el token de acceso emitido se reenvía
exactamente igual que una clave de API. issue_badge incluye un widget (ui://widget/certificate.html, MCP Apps / ChatGPT Apps SDK)
que renderiza la tarjeta del certificado. Consulta CHATGPT.md.
Privacidad y seguridad
- El servidor remoto no tiene estado. Tu clave de API se lee de la cabecera
Authorizationde cada solicitud, se reenvía aapp.issuebadge.comy nunca se almacena ni se registra. Las solicitudes sin clave reciben401. - El único host contactado es
app.issuebadge.com. El nombre del destinatario, el correo electrónico y el id de la insignia se envían allí para crear el certificado. - Política de privacidad: https://issuebadge.com/h/policy · Términos: https://issuebadge.com/h/terms · Soporte: https://issuebadge.com/h/contact
Autoalojar el servidor remoto
git clone https://github.com/issuebadge/mcp-server && cd mcp-server
npm install
npm test
npx wrangler deploy --config worker/wrangler.toml # needs a Cloudflare account
GET /health devuelve { ok: true }. Apunta ISSUEBADGE_BASE_URL a un host de API diferente para el servidor stdio si ejecutas IssueBadge en otro lugar.
Desarrollo
npm install
npm test # vitest: client, tools, worker (mocked IssueBadge API)
npm run build # tsc → dist/ (stdio bin)
npm run dev:worker
Estructura: src/issuebadge.ts (cliente de API), src/tools.ts (registro de herramientas compartido por ambos hosts), src/stdio.ts (bin de npm), src/createBadge.ts (herramienta solo stdio), worker/index.ts (Cloudflare Worker), .cursor-plugin/ + mcp.json (plugin de Cursor), .claude-plugin/ + .mcp.json (plugin de Claude Code), skills/issuebadge/SKILL.md, server.json (MCP Registry).
Licencia
MIT