walletmcppass: Apple Wallet passes

wallet-mcp：面向 Claude、ChatGPT 和任意 MCP 客户端的免费 Apple Wallet 通行证生成器

通过 AI 助手，将 PDF 登机牌、门票、优惠券或会员卡转换为已签名的 Apple Wallet 通行证（.pkpass），无需 Apple Developer 账户。wallet-mcp 是 walletmcppass.com 背后的开源服务：一个提供两个工具 create_wallet_pass 和 update_wallet_pass 的 MCP 服务，并提供相同通行证生成器的 REST API。

MCP 端点	https://walletmcppass.com/mcp（Streamable HTTP）
REST API	POST https://walletmcppass.com/api/passes、PATCH .../api/passes/{serial}
登录	无需登录，无需账户或 API 密钥
价格	每个 IP 地址每天可免费调用 30 次（创建 + 更新）；超出后每次调用收费 $0.01 USDC（Base），通过 x402 支付
限制	每天总计 500 次免费调用；付费调用：每个 IP 每天 1,000 次，总计 10,000 次；通行证最大 10 MB
通行证类型	登机牌、活动门票、优惠券、商店卡、通用卡（+ iOS 27 海报布局）
适用对象	Claude、ChatGPT、Codex、OpenAI Responses API、Claude Code、任意 Streamable HTTP MCP 客户端
输出	有效期为 1 小时的下载链接，可在 iPhone 上打开“添加到 Apple Wallet”
更新	可选：updatable=True 的通行证可在 1 小时内更新，或通过 updatable_hours 设置为最多 30 天；已安装的副本也会刷新

快速开始

Claude（网页版、桌面版和移动版；任何套餐均可使用，免费版允许添加一个自定义连接器）：打开 Customize → Connectors，点击 + Add → Add custom connector，将其命名为 walletmcppass，粘贴 https://walletmcppass.com/mcp，选择 No sign in，然后点击 Add。在聊天中，点击 + → Connectors 并启用它。完整步骤。

ChatGPT：前往 chatgpt.com/plugins，选择 + → Add custom MCP server，将其命名为 walletmcppass，在 Connection 下输入 https://walletmcppass.com/mcp，将身份验证设为无，然后选择 Create as a plugin。在聊天中，输入 @ 并选择 walletmcppass。是否可用取决于你的套餐和工作区设置。完整步骤。

Codex

codex mcp add walletmcppass --url https://walletmcppass.com/mcp

Claude Code

claude mcp add --transport http walletmcppass https://walletmcppass.com/mcp

OpenAI Responses API

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-6-astra",
    tools=[{
        "type": "mcp",
        "server_label": "walletmcppass",
        "server_description": "Creates signed Apple Wallet passes.",
        "server_url": "https://walletmcppass.com/mcp",
        "require_approval": "never",
    }],
    input="Make an Apple Wallet coupon for 20% off at Harbor Café, valid until 31 December, with the QR code CAFE20.",
)
print(response.output_text)

其他任意 MCP 客户端：添加一个远程 Streamable HTTP 服务，地址为 https://walletmcppass.com/mcp，无需添加请求头。没有 MCP 客户端？ 使用 REST API。

然后请求生成通行证：

• “根据这份 PDF 为我制作一张 Apple Wallet 登机牌。”（附上 PDF）
• “把我的攀岩馆会员卡转换成 Wallet 通行证。会员编号 004217，使用 Code 128 条形码。”
• “为 Blue Note 周五晚上 9 点的演出创建一张门票，座位 B12，二维码文本为：TICKET-0042。”

将 PDF 登机牌转换为 Apple Wallet 通行证

将航空公司的 PDF 或屏幕截图交给助手，它就会生成一张 Wallet 登机牌。登机牌使用航空公司实际签发的条形码生成：通行证包含与你的 PDF 相同的条形码数据（通常是包含 IATA BCBP 字符串的 PDF417 或 Aztec 码），供安检和登机口扫描仪读取。本服务不会签发机票、为你办理值机或联系航空公司，通行证也不会接收登机口变更信息。助手可以可靠地读取 PDF 上打印的文本，但不一定能解码条形码图像；如果无法解码，请使用条形码扫描应用扫描并粘贴文本。

与 iOS 27 中的“创建通行证”相比

iOS 27 中的 Wallet 可以扫描卡片，或在 iPhone 上填写标准、会员或活动模板，适用于单张简单的卡片。wallet-mcp 还支持：

• 登机牌、优惠券和商店卡布局、Apple 的 iOS 26 语义化登机牌，以及 iOS 27 海报布局；
• 由助手或应用根据 PDF、电子邮件或一句话生成通行证，而不是在手机上填写表单；
• 控制条码格式（QR、PDF417、Aztec、Code 128 均可使用；iOS 27 还支持 Code 39、Codabar、EAN-13、ITF）、颜色、徽标、图片和通行证背面文字；
• 可分享的签名 .pkpass 文件，也可以将其添加到未运行 iOS 27 的 iPhone 上。

隐私、条款与支持

walletmcppass.com 是一个独立项目，与 Apple 无关。通行证内容不会写入请求日志；通行证文件会在链接 1 小时后过期时删除。请求日志仅保留时间、IP 地址、通行证样式和组织名称。可更新的通行证会在其更新期限内保存（默认为 1 小时，最长 30 天），之后删除。问题和错误报告：GitHub issues。

为什么要做这个项目

手动构建 .pkpass 意味着要编写 pass.json、生成图标和徽标图稿、将每个文件的哈希值写入清单、使用 Apple Pass Type ID 证书签名，并将所有文件平铺压缩成 ZIP——这是个繁琐且容易出错的过程（参见下方的“注意事项”）。本项目将整个流程封装在一次 MCP 工具调用后，让 LLM Agent（或你通过它）只需提出生成通行证的请求。

工作原理

一个进程、一个端口，提供四项功能：

• MCP 端点（Streamable HTTP），位于 /mcp——提供 create_wallet_pass 工具。
• REST API，位于 POST /api/passes——为非 MCP 调用方提供相同的通行证构建功能。它与该工具共用速率限制和请求日志；每条日志都会记录请求的来源（source = mcp 或 api）。
• 使用情况仪表板，位于 / 和 /api/stats——显示请求数、成功／错误率和近期活动，数据均来自本地 SQLite 日志。托管实例不会公开这些内容。
• 短时有效的下载链接，位于 /download/{token}——生成的通行证使用正确的 application/vnd.apple.pkpass 内容类型提供（Wallet 识别文件所必需），并在 1 小时后过期。系统会根据文件修改时间清理文件，确保崩溃或重启不会导致文件泄露。

server.py        MCPServer instance: the tool + custom HTTP routes (REST API, dashboard, stats, downloads)
pass_builder.py  Builds pass.json per style, signs the manifest with openssl smime, zips the .pkpass
image_gen.py     Pillow-based icon/logo generation (colored square + initials / wordmark)
db.py            SQLite request log + per-IP and global daily rate limits
dashboard.html   Static dashboard page, polls /api/stats every 15s
wallet-mcp.service   Example systemd unit (Restart=on-failure, boots enabled)

工具：create_wallet_pass

标注为 title: "Create Apple Wallet pass"、readOnlyHint: false 和 destructiveHint: false：它只会创建新的通行证文件。

style: "boardingPass" | "eventTicket" | "coupon" | "generic" | "storeCard"
organization_name, description        # required
logo_text, transit_type               # transit_type only applies to boardingPass ("Air" default)
barcode_message, barcode_format       # format name or ordered list, e.g. ["EAN13", "Code128"]; omit message for no barcode
                                       # "QR" (default) | "PDF417" | "Aztec" | "Code128"; iOS 27+: "Code39" | "Codabar" | "EAN13" | "ITF"
                                       # Wallet shows the first listed format the device supports; no fallback is added
barcode_alt_text                      # human-readable text under the barcode
background_color, foreground_color, label_color   # hex "#1a1a19" or "rgb(26, 26, 25)"
relevant_date, expiration_date        # ISO 8601
locations                              # up to 10 of {latitude, longitude, altitude?, relevantText?}: show on the lock screen nearby
max_distance                           # meters; can only shrink Wallet's default radius around each location
voided                                 # stamps the pass VOID
primary_fields, secondary_fields, auxiliary_fields, header_fields, back_fields
                                       # lists of {key?, label?, value}
serial_number                         # auto-generated UUID if omitted
icon_color, icon_text, logo_color     # control the auto-generated art
icon_png_b64, logo_png_b64            # supply your own PNG instead of auto-generated art
generate_logo                          # False = no logo image (e.g. when logo_text alone is enough)

# iOS 27+
poster                                 # Poster Generic layout; style must be generic/storeCard/coupon (kept as fallback)
footer_fields                          # up to 2, poster only
background_png_b64                     # poster background (1035x1515 px); gradient auto-generated if omitted
featured_actions                       # up to 2 of {type, url}, e.g. {"type": "membershipBenefits", "url": "https://..."}

# Semantic tags and layouts
semantics                              # Apple SemanticTags dict, emitted as given; unknown keys and bad types rejected
semantic_layout                        # boardingPass (airline, iOS 26+) -> semanticBoardingPass; eventTicket -> posterEventTicket
                                       # required tags are checked; the classic style stays as the fallback, so keep its fields
info_links                             # top-level event-guide / airline-page links: bagPolicyURL, changeSeatURL, ...

# Extra images (base64 PNG); which one shows depends on style and iOS version, see the tool docstring
primary_logo_png_b64, secondary_logo_png_b64, strip_png_b64, thumbnail_png_b64, artwork_png_b64

返回 { download_url, expires_in_seconds, serial_number, pass_type_identifier }。下载链接有效期为 1 小时。请在 iPhone 上用 Safari 打开；Wallet 不会添加由其他应用传来的 .pkpass。Android 上的 Google Wallet 也可以导入同一文件。

REST API：POST /api/passes

JSON 请求体必须与上述工具参数完全一致。请求模型由同一个函数签名生成，因此二者不会出现偏差。未知键会被拒绝。

curl https://walletmcppass.com/api/passes \
  -H 'Content-Type: application/json' \
  -d '{"style": "generic", "organization_name": "Harbor Climbing Gym", "description": "Day pass",
       "primary_fields": [{"label": "Guest", "value": "Ada L."}], "barcode_message": "DAY-0042"}'

状态码	响应体
200	与工具相同：{ download_url, expires_in_seconds, serial_number, pass_type_identifier }
400	请求体格式错误或类型不匹配时返回 {"error": "invalid request", "details": [...]}；通行证本身无效时返回 {"error": "..."}
402	超出免费额度（按 IP 或全局计算）时返回 x402 PaymentRequired 响应体（也会以 base64 编码后放入 PAYMENT-REQUIRED 标头）。付款后重试，参见下文
429	返回 {"error": "rate limit exceeded: ..."} 或 "service is at its daily request limit ..."——仅在未启用付款时出现
500	{"error": "internal error building the pass"}

与工具一样，未通过架构验证的请求体会在速率限制检查前被拒绝，且不会记录日志；通行证构建错误会写入日志，并计入请求数。

更新通行证：update_wallet_pass / PATCH /api/passes/{serial}

创建通行证时设置 updatable=True，还可选择设置 updatable_hours（1 到 720，默认值为 1）来指定可更新时长。响应会新增 updatable_until 和 edit_token。edit_token 是唯一可用于修改该通行证的密钥（没有账户；持有令牌者即拥有该通行证）。通行证包含 webServiceURL（{PUBLIC_BASE_URL}/passkit）和自己的 authenticationToken，因此每台添加该通行证的 iPhone 都会向服务注册。

更新时需传入 serial_number、edit_token 和任意创建参数。传入的参数会整体替换已存储的对应参数（字段列表会替换整个列表）；未传入的参数则保留。服务会重新签署并存储通行证，然后向每台已注册设备发送空 APNs 推送。随后 Wallet 会获取新版本。设置 voided=True 即可取消通行证。如果某个字段的值发生变化，其 changeMessage（例如 "You now have %@ points"）会显示在锁屏上。Wallet 按 key 匹配字段，因此请为会变化的字段显式指定 key。

curl -X PATCH https://walletmcppass.com/api/passes/$SERIAL \
  -H "Authorization: Bearer $EDIT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"primary_fields": [{"key": "points", "label": "Points", "value": "150", "changeMessage": "You now have %@ points"}]}'

响应包含创建响应中的所有内容，以及 notified_devices 和 updatable_until（表示 APNs 已接受推送，不代表设备已完成刷新）。状态码包括 200、400、401（没有 bearer token）、402、404（序列号未知、令牌错误或更新窗口已结束；刻意使用相同状态码）和 429。更新与创建计入相同的每日限额。

备注：

• 只有可更新的通行证会存储其内容（存储在 passes 表中，编辑令牌以 SHA-256 哈希形式保存）。更新窗口从创建时开始计时，更新不会延长窗口。窗口结束后，通行证会立即视为已删除，下载清理器会在 30 秒内删除该记录及其设备注册信息。Wallet 中的副本会保留其最后一个版本。图片 URL 仅获取并存储为 PNG 一次，因此更新时不会重新获取这些图片。
• PassKit Web 服务（/passkit/v1/...）实现了 Apple 的协议：注册和注销设备、列出已更改的序列号（passesUpdatedSince 是通行证的整数 updated 时间）、获取最新通行证（If-Modified-Since 会返回 304）以及记录日志。每张通行证最多可关联 100 台设备。
• APNs 通过 curl 使用通行证签名证书，经由 HTTP/2 发送，因为 venv 中没有 HTTP/2 客户端。WALLET_MCP_APNS_URL 可覆盖端点，测试会用它指向模拟端点。如果推送收到 400 或 410 响应，则会移除该设备的令牌。
• nginx 必须将 /passkit/ 和 /api/passes/ 转发到后端，同时还要转发 /mcp、/download/ 和 = /api/passes。
• 测试：tests/test_updates.py。

图片 URL

每个 *_png_b64 参数也接受 https:// URL。image_fetch.py 会在 SSRF 防护下获取图片：仅允许 https；每个解析出的地址都必须可从公网路由（因此不允许环回、私有、链路本地或 CGNAT/tailnet 地址）；连接会固定到已检查的 IP；重定向会重新检查（最多 3 次）；限制为 5 MB、25 百万像素，每次读取最多 10 s。JPEG、WebP、GIF 和 ICO 会转换为 PNG。Base64 输入仍遵循原有规则，只允许 PNG。

部署自己的实例

你需要自己的 Apple Developer Pass Type ID 证书——本仓库设计中的证书（pass_builder.py）不会随仓库提供，也无法提供，因为它是与特定 Apple Developer 账户绑定的私钥。要部署实例：

1. 在 Apple Developer 门户中签发 Pass Type ID 证书，将私钥和签名证书导出为 PEM 格式，并下载 Apple 的 WWDR G4 中间证书。
2. 在 pass_builder.py 中，将 SIGNING_DIR/PASSKEY/CERT/WWDR 指向你的文件，并将 PASS_TYPE_IDENTIFIER/TEAM_IDENTIFIER 设置为你自己的值。
3. 配置 Python 环境（本项目除了标准工具外，不预设使用 pip/venv）：

   uv venv .venv
   uv pip install --python .venv/bin/python "mcp[cli]" pillow uvicorn starlette "x402[evm,httpx]==2.25.0"
   

4. 运行：

   PORT=8400 WALLET_MCP_PUBLIC_URL=https://your-domain/wallet-mcp \
     WALLET_MCP_PUBLIC_HOST=your-domain \
     .venv/bin/python server.py
   

   WALLET_MCP_PUBLIC_HOST 很重要：MCP SDK 默认启用了 DNS 重绑定保护，如果请求的 Host 标头不在允许列表中，就会拒绝所有请求并返回 421——请将此变量设为服务器实际使用的主机名。
5. 在前面配置带 TLS 的反向代理（nginx、Caddy 等），并对外开放 /mcp、/download/ 和 /api/passes（但不要开放 / 或 /api/stats，它们是私有仪表板）。如果使用 nginx，Streamable HTTP 传输需要：

   proxy_http_version 1.1;
   proxy_set_header Connection "";
   proxy_buffering off;
   proxy_read_timeout 3600s;
   

   必须关闭缓冲，否则 SSE 流会在代理过程中停滞。
6. 使用进程监控程序运行服务，确保它在崩溃和重启后仍能运行——本仓库中的 wallet-mcp.service 是一个可用示例（systemd、Restart=on-failure、WantedBy=multi-user.target）。

速率限制

没有 API 密钥——任何拥有 URL 的人都可以调用工具或 REST API。保护措施仅包括 db.py 中的每日上限：每个调用方 IP 每天 30 次请求，全局每天 500 次免费调用作为兜底（付费调用不计入），MCP 和 REST 调用合并计数（可通过 WALLET_MCP_IP_LIMIT / WALLET_MCP_GLOBAL_LIMIT 覆盖；WALLET_MCP_DB 用于更改 sqlite 文件位置，测试会用到该变量）。如果你将其部署在托管式 MCP 客户端（例如 claude.ai 连接器）之后，而不是直接调用，请注意，许多终端用户在服务器端可能共用一个表面上的 IP，因此每个调用方的上限无法分别限制他们——在这种情况下，真正起保护作用的是全局上限。

超出免费限额后付费：x402

将 WALLET_MCP_X402_PAY_TO 设为一个 Base 地址后，超出任一免费限额（按 IP 或全局）的调用方将获得以 $0.01 USDC 调用的选项，而不是被拒绝。付费调用不计入全局免费额度。付费调用有自己的上限：每个 IP 每天 1,000 次，总计 10,000 次（WALLET_MCP_PAID_IP_LIMIT / WALLET_MCP_PAID_GLOBAL_LIMIT），超出后将直接返回 429。未设置该选项时，调用方仍会像之前一样收到普通的 429。payments.py 使用 x402 SDK：

• MCP：被拒绝的调用会作为工具错误返回，其 structuredContent 是 x402 v2 PaymentRequired（资源为 mcp://tool/create_wallet_pass 或 update_wallet_pass）。客户端使用 _meta["x402/payment"] 中签名后的付款信息重试同一调用。随后，结果会在 _meta["x402/payment-response"] 中以及 payment 键下返回收据。
• REST：返回包含 PaymentRequired 正文和 PAYMENT-REQUIRED 标头的 402。客户端使用 PAYMENT-SIGNATURE（或旧版 X-PAYMENT）标头重试，并在 PAYMENT-RESPONSE 中以及 payment 键下收到收据。

facilitator 会在开始任何处理前验证付款。通行证生成后、交付、存储或推送之前，会在链上结算。因此，生成失败不会产生费用；结算失败（再次返回 402）则不会收到任何内容，也不会更改任何内容。在未超出限额时发送的付款会被忽略，不会扣款。每次已结算的调用都会记录其 payment_tx。服务器不会持有密钥；USDC 会直接转入收款地址。

环境变量	默认值
WALLET_MCP_X402_PAY_TO	未设置 = 关闭付款
WALLET_MCP_X402_FACILITATOR	https://facilitator.payai.network（无需账户即可在 Base 主网上结算）
WALLET_MCP_X402_NETWORK	eip155:8453（Base 主网）
WALLET_MCP_X402_PRICE	$0.01

Coinbase 的 CDP facilitator 还需要 CDP API 密钥认证标头，目前尚未接入。tests/test_x402.py 使用模拟 facilitator 运行。--live 也会向主网上的 PayAI 发送一笔无资金支持的付款，该付款必须因余额不足而被拒绝。

容量保护

这些措施可防止任何调用方（无论是否付费）导致服务器宕机：

• 超过 10 MB 的已生成通行证会被拒绝，并返回 400（WALLET_MCP_MAX_PASS_KB）。不含图片时，通行证约为 16 KB；大小主要由图片决定。
• 可用磁盘空间低于 5 GB 时，所有新建或更新请求都会收到 503（WALLET_MCP_MIN_FREE_DISK_GB）。
• 同时最多运行 4 个构建任务（BUILD_LIMITER），其余任务排队等待。图片解码是最占用内存的环节。
• wallet-mcp.service 中的 systemd 保护措施：MemoryHigh=1G、MemoryMax=1536M、CPUQuota=200%。失控的构建任务会导致该服务被 OOM 杀死并重启，而不会拖垮整台服务器。

单独运行的 cron 使用量监视器会在触发上述任一限制、systemd 重启服务，或可用磁盘空间低于 10 GB 时发送邮件。

在修改 pass_builder.py 或 image_gen.py 前值得了解的注意事项

• barcodes 是 pass.json 中的顶层键，与 boardingPass/eventTicket/等同级，而不是嵌套在样式字典中。将它嵌套在那里会被静默忽略：通行证可以正常安装，但卡片上不会显示任何条形码。
• 请明确使用 Content-Type: application/vnd.apple.pkpass 提供 .pkpass 文件。Python 的 mimetypes 模块和大多数静态文件服务器都不认识此扩展名，会回退到 application/octet-stream，导致 Wallet（以及 Mail/浏览器）将其视为普通下载，而不是提供“添加到 Apple Wallet”选项。
• 通行证各分区中的字段键必须唯一。自动生成的键过去会在每个分区中从 field0 重新开始；iOS 会直接拒绝许多此类通行证（通行证根本无法打开），但某些组合可以通过，因此问题不易察觉。现在键会加上分区前缀（primary0、secondary0、……），并在发生冲突时添加后缀。
• 交错式 2 of 5 条形码的格式字符串是 PKBarcodeFormatI2of5，而不是一些 WWDC26 文章声称的 PKBarcodeFormatITF。apple/pass-builder 是 iOS 27 键的权威参考。
• Apple 文档与 Apple 自己的 pass-builder 代码对登机牌语义时区键的说法不一致：departureLocationTimeZone（文档）与 departureAirportTimeZone（代码），目的地键也一样。两者都会被接受并按原样输出；请同时发送。
• Apple 的 Pass Builder 验证器会将不带 NFC 的海报式活动门票标记为错误，且文档指出这种设计并非用于条形码入场。NFC 需要此部署不具备的 Apple 权限，因此这类通行证可能会显示为经典活动门票。
• 某些条形码（例如许多航空公司的登机牌）是 Aztec 码，而非 QR 码——两者外观相似，但前者只有一个靶心定位图案，而不是三个角上的方块。请让 barcode_format 与实际编码格式一致。

MCP Registry

server.json 将托管实例描述为官方 MCP Registry 中的 com.walletmcppass/wallet-mcp。

状态

已上线：walletmcppass.com。有关其运行所用的部署配置，请参阅 wallet-mcp.service。