walletwallet-mcp

walletwallet-mcp lets an MCP-capable agent create and update Apple/Google Wallet passes, retrieve Google Wallet save links, and inspect WalletWallet API usage. It is a small, self-hosted bridge to the WalletWallet API, not a pass store or an authorization service.

flowchart LR
    A["Ask an agent"] --> B["Create or update a pass"]
    B --> C["Receive pass material or a save link"]
    B --> D["Installed passes may change or notify devices"]

Architecture and trust boundaries

flowchart LR
    subgraph ClientBoundary["MCP client boundary"]
        U["User"] --> C["MCP client"]
        C <--> M["Configured model provider"]
    end
    C -- "Authorization: Bearer MCP_AUTH_TOKEN" --> S["Deployed MCP server"]
    S -- "Authorization: Bearer WALLETWALLET_API_KEY" --> W["WalletWallet API"]
    W --> P["Apple / Google Wallet pass material"]
    W -. "updates may reach installed passes" .-> D["Holder devices"]

Tool arguments and results can pass through both the MCP client and its configured model provider. Review their retention, logging, and data-use settings before sending pass or customer data. The MCP bearer token stops unauthenticated HTTP requests at this server; it is never forwarded to WalletWallet. The separate WalletWallet API key is held by the server and sent only to the upstream API.

Related MCP server: Bitcoin wallet MCP server

Tool safety

Treat returned serial numbers, barcode values, customer fields, save URLs, and base64 .pkpass data as potentially sensitive. Do not put either secret—or sensitive pass data—in chat, tool arguments unnecessarily, source control, container image layers, or ordinary logs. Review every create_pass and update_pass call as a consequential external action.

Upstream non-success responses are surfaced as tool errors by httpx. get_google_wallet_link returns the upstream Location for a redirect without following it; a non-redirect success is returned as text.

Install from source

Requirements: Git and Python 3.12+.

git clone https://github.com/dhk/walletwallet-mcp.git
cd walletwallet-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp .env.example .env

Edit .env locally, then export it without printing the values:

set -a
source .env
set +a
python server.py

The streamable-HTTP endpoint is http://localhost:8000/mcp. Generate a strong, independent MCP token (for example, openssl rand -hex 32); obtain the API key from WalletWallet. Never reuse one as the other.

Run with Docker

docker build -t walletwallet-mcp:local .
docker run --rm -p 127.0.0.1:8000:8000 \
  --env-file .env \
  walletwallet-mcp:local

Binding to 127.0.0.1 keeps this first run local. For internet deployment, terminate TLS at a trusted proxy/platform and see the explicitly non-canonical provider templates.

Verify safely (no WalletWallet calls)

The automated suite uses placeholder secrets and mocked upstream responses. It checks startup configuration, missing/wrong bearer-token rejection, authenticated middleware access, request construction, redirects, and error propagation:

python -m unittest discover -s tests -v

This command makes no live WalletWallet requests and needs no production credentials. You can also start locally with placeholders to verify startup and authentication; do not invoke a tool because placeholders cannot authenticate upstream:

WALLETWALLET_API_KEY=test-not-real MCP_AUTH_TOKEN=test-not-real python server.py
curl -i http://localhost:8000/mcp
curl -i -H 'Authorization: Bearer wrong' http://localhost:8000/mcp

Both requests should return 401. Authenticated MCP initialization is a protocol request, so use an MCP inspector/client with the endpoint and correct header; the automated test exercises the same authenticated route without an upstream call.

Opt-in live smoke test (consequential)

Only after the mocked checks pass, connect an MCP client to the local endpoint with real secrets. Start with check_usage (read-only). Calling create_pass is a separate, explicit live test: it consumes quota, creates usable pass material, and can expose supplied fields and results to the MCP client/model provider. Use synthetic data and delete local outputs when done. There is deliberately no automated live test or “free” create-pass probe.

Operate safely

• Use HTTPS for every non-local endpoint; never send the bearer token over plaintext transport.

• Store both secrets in the deployment platform's secret manager, restrict operator access, and ensure request/body/header logging is disabled or redacted at the client, proxy, platform, and application layers.

• Rotate MCP_AUTH_TOKEN and WALLETWALLET_API_KEY independently. Because the MCP token is coarse-grained, rotation revokes every connected client.

• If either token or pass data may be exposed, revoke/rotate credentials, stop or isolate the service, inspect provider/access logs for misuse, assess affected passes and holders, and notify affected parties as appropriate.

• Do not expose this prototype to multiple untrusted users. OAuth, multitenancy, rate limiting, and durable audit logs are outside its scope.

See SECURITY.md for reporting vulnerabilities and CONTRIBUTING.md for the development workflow.