@aiwerk/mcp-server-pingen

Pingen hybrid mail MCP server — send physical letters, mass-mailing batches, and Swiss eBill invoices via the Pingen API.

Tools (v0.1.0, 19 tools)

Letters (8)

• pingen_letter_list — list letters with status/date filters and pagination
• pingen_letter_get — fetch a single letter by UUID
• pingen_letter_calculate_price — price estimate (currency, price) before sending
• pingen_letter_create — upload PDF and create a draft letter (auto_send hard-forced to false)
• pingen_letter_edit — update delivery settings or metadata on a draft letter
• pingen_letter_send ⚠️ — trigger postal delivery (α-gate, bulk-capable)
• pingen_letter_cancel ⚠️ — cancel a letter before printing (α-gate, bulk-capable)
• pingen_letter_delete ⚠️ — soft-delete a letter (α-gate, bulk-capable)

Letter Events (1)

• pingen_letter_list_issues — fetch validation issues for a letter (file errors, address errors)

Batches (5)

• pingen_batch_list — list mass-mailing batches
• pingen_batch_get — fetch batch details, optionally with embedded letters
• pingen_batch_create — upload PDF and create a batch (auto_send hard-forced to false)
• pingen_batch_send ⚠️ — trigger batch delivery (α-gate, bulk-capable)
• pingen_batch_cancel ⚠️ — cancel a batch (α-gate, bulk-capable)

eBill (3)

• pingen_ebill_list — list Swiss eBill submissions
• pingen_ebill_get — fetch eBill details
• pingen_ebill_create ⚠️ — submit PDF invoice to SIX eBill network (α-gate)

Organisations (2)

• pingen_organisation_list — list organisations for this account
• pingen_organisation_get — fetch organisation details and billing balance

α-gate (2-phase confirmation)

Tools marked ⚠️ require a 2-phase confirmation flow to prevent accidental billing charges or irreversible actions:

Phase 1 — call the tool without confirm_token:

{ "name": "pingen_letter_send", "arguments": { "id": "...", "delivery_product": "cheap", ... } }

Response includes requires_confirmation: true, a human-readable summary of the action, and a confirm_token (60s TTL, single-use).

Phase 2 — call again with the token:

{ "name": "pingen_letter_send", "arguments": { "id": "...", "delivery_product": "cheap", ..., "confirm_token": "<token>" } }

Bulk mode: pass ids: ["uuid1", "uuid2", ...] instead of id. One confirm_token covers all items. Phase 2 uses Promise.allSettled — partial success is reported as { succeeded[], failed[], summary }.

Configuration

Env var	Required	Default	Purpose
PINGEN_CLIENT_ID	yes	—	OAuth2 client ID from Pingen account settings
PINGEN_CLIENT_SECRET	yes	—	OAuth2 client secret
PINGEN_ORGANISATION_ID	no	auto-discovered	Organisation UUID — required for multi-org accounts
PINGEN_API_BASE_URL	no	https://api.pingen.com	Staging override: https://api-staging.pingen.com
PINGEN_IDENTITY_BASE_URL	no	https://identity.pingen.com	Staging override: https://identity-staging.pingen.com
PINGEN_API_TIMEOUT_MS	no	30000	Per-request timeout in ms

Multi-org accounts: Pingen accounts with more than one organisation must set PINGEN_ORGANISATION_ID explicitly. If omitted, the server auto-discovers (throws with the list of available org IDs if multiple are found).

Install

Option 1 — Hosted (zero setup)

No local runtime, no env vars on your machine.

1. Sign up at aiwerkmcp.com.
2. Install Pingen from the catalog and paste your PINGEN_CLIENT_ID + PINGEN_CLIENT_SECRET.
3. Point your MCP client at your hosted endpoint:

   https://bridge.aiwerk.ch/u/<your-user-id>/mcp
   

Option 2 — Self-hosted (npx)

PINGEN_CLIENT_ID=xxx PINGEN_CLIENT_SECRET=yyy npx @aiwerk/mcp-server-pingen

Or install globally:

npm install -g @aiwerk/mcp-server-pingen
PINGEN_CLIENT_ID=xxx PINGEN_CLIENT_SECRET=yyy mcp-server-pingen

Typical letter flow

1. pingen_letter_calculate_price(country="CH", paper_types=["normal"], delivery_product="cheap", ...)
   → { currency: "CHF", price: 1.48 }

2. pingen_letter_create(file_base64=<PDF>, file_name="invoice.pdf", address_position="left", ...)
   → { id: "uuid", status: "validating" }

3. pingen_letter_get(id="uuid")  →  status: "valid"  (or "action_required" if address issues)

4. pingen_letter_send(id="uuid", delivery_product="cheap", ...)
   → { requires_confirmation: true, confirm_token: "..." }

5. pingen_letter_send(id="uuid", delivery_product="cheap", ..., confirm_token="...")
   → { id: "uuid", status: "sending" }

Error taxonomy

Errors surface as MCP isError: true responses:

• Configuration error: … — missing env var, invalid URL, α-gate token expired/invalid
• Auth error (401): … — bad client credentials
• Pingen API error <status>: … — HTTP 4xx/5xx from Pingen, includes JSON:API error detail
• Pingen API timeout: … — request exceeded PINGEN_API_TIMEOUT_MS
• Network error: … — DNS/connection failure

Build / dev notes

• src/version.ts is generated from package.json by scripts/gen-version.mjs (runs as prebuild/pretest). File is committed so a fresh clone compiles immediately.
• Staging: set PINGEN_API_BASE_URL=https://api-staging.pingen.com and PINGEN_IDENTITY_BASE_URL=https://identity-staging.pingen.com.

About AIWerk MCP

Part of the AIWerk MCP platform — curated, signed MCP recipes served either as npm packages for self-hosting or through our multi-tenant hosted bridge.

Other AIWerk MCP servers:

• @aiwerk/mcp-server-wise — Wise multi-currency banking
• @aiwerk/mcp-server-imap — IMAP/SMTP email
• @aiwerk/mcp-server-cal — Cal.com scheduling

Browse the full catalog at aiwerkmcp.com.

Licence

MIT © 2026 AIWerk