PassNinja MCP server
Commit 3 Nov 2026Terbitkan dan kelola pass Apple Wallet dan Google Wallet melalui AI client menggunakan PassNinja REST API.
Juga dikenal sebagai flomio/passninja-cli, passninja-cli
- Stars
- 0
- Tools
- —
- Unduhan, 30 hari
- —
- Versi terbaru
- 0.4.0
- Commit terakhir
- 3 Nov 2026
- Lisensi
- MIT
Apa itu PassNinja MCP?
PassNinja adalah MCP server. Terbitkan dan kelola pass Apple Wallet dan Google Wallet melalui AI client menggunakan PassNinja REST API.
Ringkasan dibuat dari README proyek
Tentang PassNinja MCP server
PassNinja menyediakan cara untuk mengelola pass Apple Wallet dan Google Wallet melalui AI client. Dengan terhubung ke PassNinja REST API, developer dapat menggunakan MCP client seperti Claude Desktop untuk menerbitkan, memperbarui, dan menghapus digital pass atau mengelola template pass. Server ini menyediakan 31 tools berbeda yang mencakup segalanya, mulai dari manajemen webhook hingga aplikasi scan-event dan konfigurasi reader.
Untuk menyiapkan server, Anda memerlukan API key dan account ID dari pengaturan PassNinja Anda. Meskipun server dapat menggunakan sesi login lokal yang dibuat melalui command-line interface, server ini utamanya mengandalkan environment variables untuk autentikasi di lingkungan otomatis. Hal ini memungkinkan AI untuk berinteraksi langsung dengan infrastruktur pass Anda, melakukan tugas seperti menampilkan daftar template, memeriksa jumlah pass yang terpasang pada template tertentu, atau menerbitkan pass baru ke alamat email tertentu.
Apa yang bisa Anda lakukan dengannya
- 1Audit penggunaan template passMinta AI untuk menampilkan semua template pass yang tersedia dan melaporkan jumlah pass yang terpasang untuk masing-masing template.
- 2Terbitkan digital pass baruInstruksikan AI untuk membuat pass baru bagi pengguna tertentu menggunakan template ID yang telah ditentukan.
- 3Kelola konfigurasi webhookGunakan AI untuk membuat atau menghapus webhook yang merespons event pass tertentu.
Ditulis berdasarkan README proyek. Setiap use case diperiksa terhadap kutipan dari README tersebut.
Konfigurasi
PASSNINJA_API_KEY
| Nama | Deskripsi | Tipe |
|---|---|---|
| PASSNINJA_API_KEY | — |
Pengecekan otomatis
Berjalan 14 Nov 2026Laporan lengkap →Belum diverifikasi. Sebuah server memerlukan skor 80, tidak ada temuan serius, dan data yang cukup untuk kami periksa. Cara kerja checks · Yang perlu diperbaiki untuk menambah poin
- Source repository terhubung dan dapat dijangkauflomio/passninja-cli is public and reachablegithub.com/flomio/passninja-cli ↗Lolos
- Nama paket mencantumkan repositori ini sebagai sumbernyaTidak diperiksa
- Provenance build (atestasi Sigstore)Tidak diperiksa
- Lisensi open source (OSI)MITspdx.org/licenses/MIT.html ↗Lolos
- Ada commit atau release dalam satu tahun terakhirLast commit or release 2026-11-03github.com/flomio/passninja-cli ↗Lolos
- OpenSSF ScorecardTidak diperiksa
- Nama package tidak mirip dengan package populerTidak diperiksa
- Tidak ada advisory kritis pada paket atau dependensinyaTidak diperiksa
- Tidak ada instruksi tersembunyi untuk model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersLolos
- Tools yang bersifat destruktif telah diberi labelTidak diperiksa
- Endpoint remote merespons handshake MCPTidak diperiksa
README
Lihat di GitHubpassninja
Command-line interface for the PassNinja REST API.
Wraps /v1/pass_templates, /v1/passes, and /v1/webhooks so you can
manage Apple Wallet and Google Wallet passes from the shell.
Install
macOS / Linux (Homebrew)
brew tap flomio/passninja
brew install passninja
Windows (PowerShell)
irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex
From cmd.exe:
powershell -ExecutionPolicy Bypass -Command "irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex"
The script detects your CPU (amd64, arm64, or 386), downloads the matching
binary from the latest GitHub release, verifies its SHA256, drops it in
%LOCALAPPDATA%\Programs\passninja\, and adds that directory to your user
PATH. No admin needed; re-running upgrades in place.
Pin a specific version, or override the install directory:
$env:PASSNINJA_VERSION = 'v1.2.3'
$env:PASSNINJA_INSTALL_DIR = 'C:\tools\passninja'
irm https://github.com/flomio/passninja-cli/releases/latest/download/install.ps1 | iex
Windows (Scoop)
If you already use Scoop:
scoop bucket add flomio https://github.com/flomio/scoop-passninja
scoop install passninja
Claude Desktop (one-click .mcpb install)
For chat-driven pass workflows, install the PassNinja MCP server into Claude Desktop:
-
Download
passninja.mcpbfrom the latest release. -
Double-click the file. Claude Desktop opens an install dialog showing the 31 tools the server exposes (pass templates, issued passes, webhooks, scan-event applications and readers).
-
The dialog prompts for your API key and account ID — get them at https://www.passninja.com/settings → API key.
-
Hit Install, restart Claude Desktop, then ask Claude things like:
List my passninja pass templates and tell me how many passes are installed on each.
Issue a new pass on ptk_0x002 for jane@example.com.
The bundled binary is code-signed with Apple Developer ID and notarized, so
macOS Gatekeeper accepts it without prompts. Same .mcpb works on macOS
(universal), Linux (amd64), and Windows (amd64).
The server is also listed in the official MCP Registry
as io.github.flomio/passninja-cli, so any MCP client that consumes the
registry can discover and install it automatically.
Authenticate
passninja login
# Opens www.passninja.com in your browser. If you're already signed in there,
# no password is asked. The CLI keeps a login session in your OS keychain —
# never your account API key.
The session's access token refreshes automatically; the session itself ends
30 days after login, and passninja logout ends it immediately (locally and
on the server). If you run any command while logged out at a terminal, the
browser login starts on its own.
On a machine without a browser (SSH, containers), log in with a code entered from any other device:
passninja login --device
For CI and scripts, use an API key via env / flags instead:
export PASSNINJA_API_KEY=... PASSNINJA_ACCOUNT_ID=aid_0x002
passninja --api-key=... --account-id=... pass-template list
Precedence: API key (flags > env > ~/.passninja.yaml) > login session >
legacy ~/.passninja-auth.json (written by passninja auth). An API key you
set explicitly always wins, so automation is never redirected to a personal
session.
The same precedence applies to the MCP server: passninja mcp (started by
Claude Desktop and other MCP clients) uses PASSNINJA_API_KEY /
PASSNINJA_ACCOUNT_ID from its environment, else your login session. It
never opens a browser itself — run passninja login once first.
Stdio MCP server
The CLI also doubles as a Model Context Protocol
server. The .mcpb install above wires this into Claude Desktop, but you can
hook it into any MCP client (Cursor, Cline, Zed, etc.) by configuring the
client to launch:
passninja mcp
Tool surface (snake_case names mirror the CLI subcommands):
whoami
pass_template_{list, get, required_fields, reader_config, create, delete}
pass_{list, get, create, update, delete, raw, decrypt}
webhook_{list, get, create, delete, results}
Each tool's input schema, destructive-hint annotations, and rich descriptions let the LLM self-discover correct usage without external documentation.
Commands
passninja login [--device] [--no-browser] Log in through your browser (session in OS keychain)
passninja logout End the login session here and on the server
passninja auth Save an API key to ~/.passninja-auth.json (legacy)
passninja whoami Show the active credential / account
passninja version
passninja pass-template list
passninja pass-template get <ptk_0x...>
passninja pass-template required-fields <ptk_0x...>
passninja pass-template reader-config <ptk_0x...> # NFC reader config (merchant id, collector, EC keys)
passninja pass-template create --name --platform --style [config flags] # enterprise only
passninja pass-template update <ptk_0x...> [--name --set --remap --show/--hide --require/--optional] [config flags] [--replace] # enterprise only
passninja pass-template delete <ptk_0x...> [--yes] # enterprise only
# config flags (create + update): --constrain-device/-browser/-ip,
# --disable-apple-sharing/-google-sharing, --auto-recharge --balance-trigger --top-up-target
passninja pass create <ptk_0x...> [--field k=v | --data @file.json | --data '<json>']
passninja pass list <ptk_0x...>
passninja pass get <ptk_0x...> <pass_id>
passninja pass raw <ptk_0x...> <pass_id>
passninja pass update <ptk_0x...> <pass_id> [--field k=v | --data ... | --replace]
passninja pass delete <ptk_0x...> <pass_id> [--yes]
passninja pass decrypt <ptk_0x...> [--payload <hex> | --payload-file <path> | <stdin>] [--platform apple]
# Google Smart Tap is session-bound — use `reader serve` on the reader host
# Enterprise only:
passninja webhook create --name --url --event <type> [--event <type> ...] [--pass-template ptk_0x...]
passninja webhook list [--page --per-page --pass-template]
passninja webhook get <webhook_id>
passninja webhook delete <webhook_id> [--yes]
passninja webhook results <webhook_id> [--page --per-page]
# Scan event system (premium):
passninja application list
passninja application get <app_0x...>
passninja application create --name --pass-template ptk_0x... [--kind log|validate|forward]
[--rescan-window <seconds>] [--endpoint-url <https>] [--bearer-token <secret>]
[--timeout-ms <100-8000>] [--on-endpoint-error accept|reject] [--description]
passninja application update <app_0x...> [--name --description --kind --rescan-window --endpoint-url
--bearer-token --timeout-ms --on-endpoint-error --active/--inactive]
passninja application delete <app_0x...> [--yes]
passninja reader list
passninja reader get <reader_id>
passninja reader create --name --location --application app_0x... [--application ...] # prints the token once
passninja reader update <reader_id> [--name --location --status active|revoked --application ...]
passninja reader rotate-token <reader_id> [--yes]
passninja reader delete <reader_id> [--yes]
passninja reader config <reader_id> # merged reader config across bound templates
passninja reader serve --token rdr_... [--pcsc [--pcsc-reader <name>] | --listen host:port]
[--platform apple|google] [--heartbeat 5m | --no-heartbeat]
[--serial --manufacturer --model --firmware --source]
[--on-accept '<cmd>'] [--on-reject '<cmd>']
Output formats
| Flag | Mode |
|---|---|
--json |
Pretty-printed JSON |
--plaintext |
Tab-separated, no decoration (good for piping to awk) |
| default | Bordered ASCII table |
Set a session-wide default via ~/.passninja.yaml:
default_output: json # one of: table | json | plaintext
base_url: https://api.passninja.com/v1
Webhook events
The CloudEvents 1.0 type taxonomy emitted by passninja-site:
| Event type | When it fires |
|---|---|
pn.pass.installed |
First device installs an issued pass |
pn.pass.updated |
Pass fields change via PATCH/PUT |
pn.pass.uninstalled |
Last device removes the pass |
pn.pass.scanned |
A reader records a scan event (carries scanId, readerSerial, result) |
Reserved for future use: pn.pass.issued, pn.pass.deleted,
pn.pass_template.created, pn.pass_template.updated,
pn.pass_template.deleted.
Running a reader host
Cloud-connected readers (VTAP Cloud, Famoco Tap&Go) post scans to PassNinja
themselves. A simple reader — Reyax RYRR30D, ACS WalletMate, Elatec TWN4 —
has no cloud connection of its own, so reader serve supplies one: it takes
the values the reader captures, submits them as scan events, and applies the
LED/beep instruction the server returns.
Setup is three steps, and only the last one runs on the reader host:
# 1. an application decides what a scan means for one pass template
passninja application create --name "Front gate" --kind validate \
--pass-template ptk_0x216 --rescan-window 14400
# 2. a reader binds to it; the token is printed once — save it
passninja reader create --name "Front gate" --location "Gate 2" \
--application app_0x1
# 3. on the reader host (a Raspberry Pi, a kiosk PC, …)
passninja reader serve --token rdr_... --pcsc # attached PC/SC reader
my-reader-daemon | passninja reader serve --token rdr_... # or any daemon
serve authenticates as that one reader with its bearer token — a reader
host never needs, and should never hold, your account API key.
Tap values arrive from one of three sources:
--pcscdrives an attached PC/SC contactless reader (ACS WalletMate / WalletMate II, incl. the Mini module) directly — no separate daemon. The host runs the wallet flows itself: on an Apple tap it captures the VAS cryptogram; on an Android tap it has the server pre-sign the Smart Tap session mid-tap (the collector key never leaves PassNinja), negotiates the secure channel, and captures the encrypted bundle. Both are submitted for server-side decryption — the host holds no key material. First-generation WalletMates ship with RF polling disabled;serveenables it automatically when the vendor CCID driver is installed. Needs a native (cgo) build on macOS/Linux —go installand Homebrew builds qualify.- stdin (one value per line) — pipe any reader daemon's output in.
--listen 127.0.0.1:8080— a loopback HTTP endpoint a driver POSTs to.
For stdin/HTTP, a value that looks like raw captured APDUs is forwarded for server-side decryption; anything else is treated as an already-decrypted pass serial.
Each result is one JSON object on stdout:
{"scanId":"9f8e7d6c-…","result":"accepted","pass":{"passTemplate":"ptk_0x216","passId":"fee4a257185906b92a"},
"readerInstructions":{"success":true,"led":"green","beep":true,"message":"Accepted"}}
To drive a physical LED, use the outcome hooks — they receive $PN_RESULT,
$PN_LED, $PN_MESSAGE, $PN_PASS, $PN_SCAN_ID, and — when a forward
application answered — $PN_FORWARD_BODY (the endpoint's JSON reply). On a
forward application, $PN_MESSAGE is the endpoint's message verbatim and
the printed scan JSON carries the reply under forwardResponse:
passninja reader serve --token rdr_... \
--on-accept 'gpioset 0 17=1' --on-reject 'gpioset 0 27=1'
Heartbeats (default every 5m) report liveness plus the hardware identity you
pass with --serial / --manufacturer / --model / --firmware, which is
what fills in the reader's Hardware panel in the dashboard. Readers whose
vendor MDM already tracks them should use --no-heartbeat.
passninja webhook create returns the bearer token once on creation.
Save it — it will not be shown again.
Build from source
git clone https://github.com/flomio/passninja-cli.git
cd passninja-cli
make build # writes dist/passninja
./dist/passninja version
make install # installs to $GOPATH/bin
Release flow
Tag-driven. Push a vX.Y.Z tag on master; the GitHub Actions workflow at
.github/workflows/release.yml matrix-builds darwin/linux × arm64/amd64,
packages a code-signed + Apple-notarized passninja.mcpb on a macOS runner,
publishes both the binaries and the .mcpb on the GitHub Release, and opens
a PR against flomio/homebrew-passninja bumping the formula url and
sha256.
Apple credentials live in repo secrets (APPLE_TEAM_ID,
APPLE_API_KEY_ID, APPLE_API_ISSUER_ID, APPLE_SIGN_IDENTITY,
APPLE_CERTIFICATE_PASSWORD, plus the base64-encoded APPLE_API_KEY_P8
and APPLE_CERTIFICATE_P12).
After each tagged release, the MCP Registry entry needs a refresh. Bump
packages[0].identifier, packages[0].version, packages[0].fileSha256,
and the top-level version in server.json to match the new release, then:
mcp-publisher login github # one-time per machine
mcp-publisher publish
Pertanyaan tentang PassNinja MCP
Bagaimana cara install PassNinja MCP server di Claude Desktop?
Anda dapat melakukan instalasi satu klik dengan mengunduh file 'passninja.mcpb' dari rilis terbaru dan melakukan double-click pada file tersebut.
Metode autentikasi apa saja yang didukung?
Server ini mendukung API keys dan account ID yang diberikan melalui environment variables atau flags, serta sesi login lokal yang tersimpan di OS keychain Anda.
Bisakah saya menggunakan PassNinja di lingkungan headless seperti SSH atau container?
Ya, Anda bisa login menggunakan device code yang dimasukkan melalui perangkat lain dengan menggunakan flag '--device'.