Issuebage MCP Server
官方数字徽章发行平台
你可以用 Issuebage MCP 做什么?
- 验证你的 API 密钥 — 让你的助手使用
validate_key检查你的 IssueBadge 凭据是否有效。 - 列出徽章模板 — 获取你可用的徽章模板,以便在颁发前选择正确的模板。
- 颁发证书 — 通过姓名和电子邮件向收件人发送证书,并返回一个公开验证 URL。
- 检查二维码 — 列出动态二维码、获取某个二维码及其 PNG 图像,或查看其扫描历史。
- 删除二维码 — 通过其代码删除现有的动态二维码。
文档
IssueBadge MCP 服务器
从任何 AI 代理颁发可验证的证书和徽章。此 Model Context Protocol 服务器让 Cursor、Claude、VS Code 和其他 MCP 客户端能够列出你的 IssueBadge 徽章模板,并通过姓名和电子邮件向收件人发送证书。
有两种运行方式:
| 远程(推荐) | 本地(stdio) | |
|---|---|---|
| 端点 | https://issuebadge-mcp.issuebadge.workers.dev/mcp | npx issuebadge-mcp-server |
| 认证 | Authorization: Bearer <API key> 请求头 | ISSUEBADGE_API_KEY 环境变量 |
| 工具 | validate_key、get_all_badges、issue_badge、list_qr_codes、get_qr_code、get_qr_code_scans、delete_qr_code | 相同 + create_badge |
| 存储 | 无,无状态 | 无 |
你需要一个 IssueBadge API 密钥:app.issuebadge.com → Developer → API key(https://app.issuebadge.com/developer/index)。
安装
Cursor
从 Cursor Marketplace 安装 IssueBadge,并在提示时粘贴你的 API 密钥。或者在 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"
此仓库也是一个 Claude Code 插件(.claude-plugin/plugin.json),并附带一个 issuebadge 技能,用于教会代理“列出 → 确认 → 颁发”的工作流程。该插件的 .mcp.json 从 ISSUEBADGE_API_KEY 环境变量读取密钥,因此在启动 Claude Code 之前请先导出该变量。
Claude Desktop / 任何 stdio 客户端
{
"mcpServers": {
"issuebadge": {
"command": "npx",
"args": ["-y", "issuebadge-mcp-server"],
"env": { "ISSUEBADGE_API_KEY": "YOUR_ISSUEBADGE_API_KEY" }
}
}
}
VS Code(Copilot 代理模式)
.vscode/mcp.json:
{
"servers": {
"issuebadge": {
"type": "http",
"url": "https://issuebadge-mcp.issuebadge.workers.dev/mcp",
"headers": { "Authorization": "Bearer YOUR_ISSUEBADGE_API_KEY" }
}
}
}
工具
| 工具 | 输入 | 返回 |
|---|---|---|
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(仅 stdio) | name、description、issuing_organization_name、idempotency_key、可选的 badge_logo_path、custom_fields、… | IssueBadge API 响应 |
issue_badge 会将证书通过电子邮件发送给收件人,并返回一个公开验证 URL。每次使用新的 idempotency_key 调用都会颁发一张新证书(如果你省略它,则会生成一个作为 mcp-<uuid>)。API 会拒绝重复使用的密钥,因此调用失败后,请先检查证书是否已颁发,然后再用新密钥重试。
安装后的示例提示:“将课程完成证书颁发给 Jane Doe,jane@example.com。”
动态二维码
| 工具 | 输入 | 返回 |
|---|---|---|
list_qr_codes | type?、limit? | { qr_codes: [...], total } |
get_qr_code | code | 二维码 + PNG 图像块 |
get_qr_code_scans | code、limit? | { code, scan_count, scans: [{ scanned_at, referer }], total } |
delete_qr_code | code | { deleted: true, code } |
类型:url、vcard、paypal、wifi、email、phone、sms、maps、event、facebook、twitter、youtube、text、mecard。二维码在 IssueBadge 仪表板中创建和重定向;图像编码的是一个 IssueBadge 重定向(scan_url),因此当目标地址发生变化时,已打印的二维码仍可继续使用。
示例提示:“创建一个名为 Menu 的二维码,打开 https://example.com/menu 并展示给我看。”
ChatGPT 和 OAuth
远程服务器还支持 OAuth 2.1,适用于无法发送 API 密钥的主机(ChatGPT 应用、Claude 连接器):不带 bearer 的请求会收到 401 + WWW-Authenticate: Bearer resource_metadata=…,/.well-known/oauth-protected-resource 指向 https://app.issuebadge.com(PKCE S256,动态客户端注册),并且颁发的访问令牌会像 API 密钥一样被原样转发。issue_badge 携带一个组件(ui://widget/certificate.html,MCP Apps / ChatGPT Apps SDK),用于渲染证书卡片。参见 CHATGPT.md。
隐私与安全
- 远程服务器是无状态的。你的 API 密钥从每个请求的
Authorization请求头中读取,转发到app.issuebadge.com,并且从不存储或记录日志。不带密钥的请求会收到401。 - 唯一联系的主机是
app.issuebadge.com。收件人姓名、电子邮件和徽章 ID 会发送到那里以创建证书。 - 隐私政策:https://issuebadge.com/h/policy · 条款:https://issuebadge.com/h/terms · 支持:https://issuebadge.com/h/contact
自托管远程服务器
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 返回 { ok: true }。如果你在其他地方运行 IssueBadge,请将 ISSUEBADGE_BASE_URL 指向不同的 API 主机以用于 stdio 服务器。
开发
npm install
npm test # vitest: client, tools, worker (mocked IssueBadge API)
npm run build # tsc → dist/ (stdio bin)
npm run dev:worker
目录结构:src/issuebadge.ts(API 客户端)、src/tools.ts(两个主机共享的工具注册表)、src/stdio.ts(npm bin)、src/createBadge.ts(仅 stdio 工具)、worker/index.ts(Cloudflare Worker)、.cursor-plugin/ + mcp.json(Cursor 插件)、.claude-plugin/ + .mcp.json(Claude Code 插件)、skills/issuebadge/SKILL.md、server.json(MCP Registry)。
许可证
MIT