epost-mcp

Read, download and archive your Swiss ePost digital letterbox — over the documented public API, with browser automation as a fallback.

     

Unofficial. Not affiliated with ePost or Swiss Post. It speaks their documented public API where it can and falls back to driving the web portal where it cannot — that fallback is inherently fragile, since portal updates break selectors without warning. Use it for your own letterbox and respect the provider's terms of service.

An MCP server for the Swiss ePost digital letterbox (app.epost.ch). It lets an MCP client (Claude Code, Claude Desktop, …) list and download your scanned letters and do basic housekeeping in the ePost Storage area — folders and moving documents.

ePost does publish a public API for the Digital Letterbox, and a private tenant can use it — see Transport below. That is the preferred path: no browser, no session, and letters arrive with a real sender description. Browser automation via Playwright remains for the few things the API does not cover.

How a call gets answered

Two ways in, and the server picks per call rather than per session — so the same conversation can read a letter over the API and archive it in the browser without you arranging anything. EPOST_TRANSPORT pins that choice if you would rather it did not move.

flowchart TD
    C["MCP client<br/>(Claude Code, Claude Desktop, …)"] -->|"stdio JSON-RPC"| S["epost-mcp"]

    S --> T{"EPOST_TRANSPORT"}
    T -->|"api — pinned"| A
    T -->|"browser — pinned"| B
    T -->|"auto (default)"| D{"Does this call<br/>reach for a page?"}
    D -->|"no"| A["REST call to api.epost.ch"]
    D -->|"yes — and only then<br/>is a browser launched"| B["Playwright drives<br/>app.epost.ch"]

    K1["account password<br/>keychain: epost-mcp-api-password"] -->|"password grant"| KC["Keycloak token"]
    KC -.->|"Authorization: Bearer"| A
    K2["API key<br/>keychain: epost-mcp-api-key"] -.->|"X-API-KEY"| A
    A --> E[("ePost<br/>Digital Letterbox")]
    B --> E

    subgraph disk["on disk — a live letterbox session, and secret"]
        P["Chromium profile<br/>~/.epost-mcp/profile"]
        ST["storageState<br/>~/.epost-mcp/state.json"]
    end
    disk -.->|"seeds the context"| B
    B -.->|"state.json re-saved after<br/>every successful call"| ST
    L["epost_login<br/>visible window, one Touch ID"] -.->|"fills state.json once"| ST

    classDef pin fill:#fff4e5,stroke:#d9822b
    classDef store fill:#fdecea,stroke:#c0392b
    class T,D pin
    class P,ST store
    style disk fill:#fbfbfb,stroke:#999,stroke-dasharray: 4 3

A pin is enforced both ways. Pinned to api, a browser-only tool is refused rather than quietly redirected — the point of pinning is knowing what ran.

Related MCP server: mcp-chrome-server

Prerequisites

• Node.js ≥ 20.19

• A Chromium managed by Playwright

• A Swiss ePost account with the Scanning-Service, reachable via SwissID

git clone https://github.com/sapn95/epost-mcp.git
cd epost-mcp
npm install
npx playwright install chromium   # downloads the browser Playwright drives

Session / login model

The hard part of ePost automation is the login. This server keeps you logged in so you do not re-authenticate on every call or every restart:

• The SwissID/ePost session is cached as a Playwright storageState file at ~/.epost-mcp/state.json (49 cookies incl. the KLARA/Keycloak SSO cookies).

• On startup the server loads that file, so a previously logged-in session is reused across server restarts.

• After a successful epost_login and after every successful tool call, the server re-saves state.json, keeping the cached session fresh.

• epost_login opens a visible (headed) browser window so you complete the SwissID login (incl. 2FA) yourself. Every other tool runs headless.

• SwissID sessions are short-lived. When the session expires, tools return login_required — just run epost_login again.

First-time / after-expiry flow:

1. Call epost_status. If it returns login_required…

2. …call epost_login. A browser window opens on app.epost.ch. Complete the SwissID login until you see your dashboard / the letterbox. The session is then cached to ~/.epost-mcp/state.json.

3. Use epost_list_letters, epost_download_letter, etc. headlessly.

Security: ~/.epost-mcp/state.json contains live session cookies for your ePost/SwissID account. Treat it like a password. It is git-ignored in this repo and must never be committed, shared, or synced to a cloud folder. Delete it to force a fresh login. Override its location with EPOST_STATE.

Transport: the public API, with the browser as fallback

ePost publishes a REST API for the Digital Letterbox, and a private tenant can use it — which is easy to miss, because the developer portal is written for business clients. The API is preferred for everything it covers; browser automation runs only when it cannot serve a call.

Set it up once:

1. Log in to app.epost.ch with SwissID as usual.

2. In the same browser, open https://login.epost.ch/auth/realms/klara/account/ → Authentication → Set/update password, and set one. A SwissID login has no password of its own, which is the whole point of this step.

3. Store it: security add-generic-password -a epost -s epost-mcp-api-password -w -U — -w with no value prompts, so the password never reaches your shell history or a process listing. (or set EPOST_API_PASSWORD). The account e-mail comes from the same place as before.

Documented at How to access the letterbox public APIs with a private tenant.

Why it is worth it

Measured against the same account:

That second row is the one that matters: the portal renders every scan with the same title, so an archived document could not be classified without opening it. The API has carried the sender all along.

What the API does not do

There is no endpoint to move a document that is already in Storage between folders. PATCH /letters/{id}/archive is inbox → folder only and answers 400 for anything already archived — the documentation says so explicitly. Re-filing therefore falls back to the browser.

A useful division follows from that: the browser acts, the API checks. The move itself is not verified for you — epost_move_to_folder reports what the portal accepted, not what it ended up holding. Run epost_list_storage_documents afterwards and the API says which document id is in which folder, which matters because Storage cards show only a date, and dates repeat.

Auth: two schemes, both supported

The API documents an API key and Bearer auth, and this server does both.

Password grant (what the private-tenant guide describes):

POST /core/latest/tenants   {username, password}                     -> tenant_id, company_id
POST /core/latest/token     {username, password, grant_type=password,
                             tenant_id, company_id}                  -> access_token (600s)
GET  /epost/v2/letters      Authorization: Bearer …

It re-authenticates a minute before expiry rather than tracking refresh tokens: the password is already at hand, so a refresh buys nothing.

API key, as an alternative or in addition:

# -w with no value prompts, so the key stays out of shell history and argv
security add-generic-password -a epost -s epost-mcp-api-key -w -U
# or: export EPOST_API_KEY=<key>

Sent as X-API-KEY. A key on its own is a complete credential — the password grant is then skipped entirely, which is the simpler setup if you have one. When both are configured the key travels alongside the token, matching the portal's own examples.

epost_settings reports which of the two are in play.

Choosing the transport

EPOST_TRANSPORT is auto by default: the API answers whatever it can, the browser takes the rest. Pin it to api or browser to diagnose a result, or to force the browser for the one thing only it can do.

Login: one fingerprint, nothing else

epost_login drives every step of the SwissID chain that does not need a human and stops at the only one that does — the biometric prompt:

app.epost.ch → login.epost.ch     clicks "Login mit SwissID"
             → login-email         fills your account e-mail, "Weiter"
             → confirm-passkey     "Weiter"   → macOS asks for Touch ID   ← you
             → app.epost.ch, authenticated; session cached

Measured end to end: 19 seconds, one fingerprint, no password and no SMS code. Two things have to be in place:

1. A passkey on your SwissID account, created normally in Safari or Chrome (account.swissid.ch → Login-Einstellungen). Apple's authenticator is accepted; see the note below for why a software one is not.

2. A signed browser. Playwright's bundled Chromium is an unsigned test build and reports isUserVerifyingPlatformAuthenticatorAvailable() === false, so Touch ID is never offered and SwissID falls back to password + SMS. Installed Google Chrome reports true. The server therefore prefers a signed system browser automatically — chrome, chrome-canary, edge, brave, in that order — and falls back to the bundled Chromium. Override with EPOST_BROWSER.

Tell it which account to fill in, either way:

security add-generic-password -a epost -s epost-mcp-swissid-user \
  -w 'you@example.com' -U          # or: export EPOST_SWISSID_USER=you@example.com

epost_settings prints what was resolved — browser, passkey capability, paths, and whether the account e-mail is configured. Run it first if a login surprises you.

Why the login is not fully unattended

Everything except the biometric prompt is driven. That is the ceiling, not a shortcoming of the implementation: a passkey cannot be used without genuine user presence.

The tempting shortcut — a software passkey through Chrome's WebAuthn virtual authenticator, so the server could sign the login itself — was built, tried, and removed. SwissID rejects software authenticators outright:

POST /api-login/authenticate/webauthn-register  ->  400
ERROR::WebauthnVendorNotAllowed

It was removed rather than kept "just in case": it could never work against the one service this server talks to, and it wrote an exportable private key into the login keychain — a standing risk in exchange for nothing.

Register in Claude Code

Use an absolute path to index.js:

claude mcp add epost --scope user -- node /absolute/path/to/epost-mcp/index.js

Or add it directly to ~/.claude.json:

{
  "mcpServers": {
    "epost": {
      "command": "node",
      "args": ["/absolute/path/to/epost-mcp/index.js"]
    }
  }
}

(Claude Desktop uses the same shape in its claude_desktop_config.json.)

Tools

Notes on the Storage tools

The Storage area (LetterStorage) has auto Companies folders (grouped by sender, e.g. ePost / la Mobilière), your Custom folders, and the master My Documents (N) list. epost_list_storage returns your Custom folders and the My-Documents count; epost_list_storage_documents enumerates the individual documents (each only exposes a date + a Stored in <folder> tag once filed).

Archiving a letter (epost_store_letter)

Store in the card menu is a two-step action: it opens a Select a folder sheet carrying its own Store button, greyed out until a folder is ticked. That is why a folder argument is required — without one the sheet cannot commit, and stopping after the first click archives nothing while leaving an invisible overlay that swallows every later click.

Three things inside that sheet make a folder that is plainly there look absent, all of them handled now but worth knowing if it ever regresses:

• .brand-container also matches the letter cards behind the sheet, so the lookup has to be scoped to the sheet element.

• The tiles sit in a horizontally scrolling strip, so filtering on visibility drops every folder off to the right.

• Folder names must be compared NFC-normalised: a name with an umlaut is NFC on one side and NFD on the other, and a byte-exact compare never matches.

ePost folders are additive labels, not physical locations. My Documents always lists every document; filing simply adds a folder membership (a document can belong to several folders at once). epost_move_to_folder reflects this: it opens the document's … menu → Move → ticks the target folder → confirms, and is idempotent — a no-op if the document is already in that folder, and it never removes an existing membership. Two consequences worth knowing:

• Filing bumps a document to the top of the Last used order, so re-list before addressing the next document by index (indices shift after a move).

• The portal's Move sheet will not commit an empty folder set, so a document that is in exactly one folder cannot be returned to "unfiled" through this flow — you can only re-file it elsewhere (or delete it) in the ePost UI. In other words, filing is effectively one-way; get the target right first.

Environment variables

The browser is resolved in that order deliberately: an installed, signed browser first, because only that one can reach the platform authenticator, and only then Playwright's own Chromium and the Playwright cache (~/Library/Caches/ms-playwright/chromium-*). epost_settings reports which was chosen and why.

Troubleshooting

• Tools return login_required. The cached session expired (SwissID sessions are short-lived). Run epost_login and complete SwissID; the session is re-cached. If it keeps happening immediately, delete ~/.epost-mcp/state.json and log in fresh.

• epost_login window never appears. epost_login is the only tool that runs headed. If nothing opens, another instance may hold the browser — stop other MCP clients using this server, then retry.

• Chromium not found. Run npx playwright install chromium, or set EPOST_CHROMIUM to the executable path, e.g. on macOS: ~/Library/Caches/ms-playwright/chromium-<build>/chrome-mac/Chromium.app/Contents/MacOS/Chromium.

• Download does not trigger. The server clicks the portal's Download File button and captures the browser download event. If it times out, ePost likely changed the letter-detail layout; the button is matched by its visible text and [aria-label="Download File"]. Re-run epost_list_letters first to confirm the letterbox is reachable.

• Selectors broke after an ePost release. This automation tracks the live DOM (div.letter-wrapper, Digital Letterbox, Go to Storage, Download File). Portal changes can break it; open an issue.

How it works (internals)

1. chromium.launchPersistentContext(EPOST_PROFILE, …) with acceptDownloads: true and locale: 'de-CH', and the cookies from state.json are then added on top. Both halves are needed: the profile keeps what a fresh context throws away, notably SwissID's "this device is known" state, while state.json keeps the session cookies, which a persistent profile drops when the browser closes. Running on storageState alone is what made every expiry cost the full two-factor dance again.

2. Navigating to app.epost.ch follows the KLARA/SwissID SSO redirect chain onto the dashboard (or a visible login form if the session died).

3. The letterbox is opened by clicking the Digital Letterbox label (URL then contains DigitalLetterboxOverview).

4. Letters are div.letter-wrapper elements. Downloads iterate on the same page: click letter → Download File → save → Escape back to the list.

Releasing

Published from CI with npm Trusted Publishing (OIDC) — there is no npm token anywhere: no secret to store, rotate or leak. npm recommends this over an automation token, and is restricting tokens that bypass 2FA.

One-time setup per package, on npmjs.com -> the package -> Settings -> Trusted Publisher:

The workflow filename must match exactly. That is deliberate: it stops any other workflow in the repo from publishing under your name.

Then every release is one command:

npm version patch && git push --follow-tags

The tag triggers the release workflow: it upgrades npm (trusted publishing needs

= 11.5.1 and Node >= 22.14), refuses a tag whose version disagrees with package.json, runs the gate, and publishes with a signed provenance statement.

If the publish fails with 404

npm notice publish Signed provenance statement ... from GitHub Actions
npm error 404 Not Found - PUT https://registry.npmjs.org/epost-mcp

Provenance was signed, so OIDC worked — the registry simply does not accept this workflow as a publisher yet. That means the trusted publisher is not configured, or the repository / workflow name does not match. npm answers 404 rather than 403 so as not to reveal whether the package exists. It is not a credential problem: there is no credential, by design.

Checks

npm run gate      # lint + smoke + hygiene + tests with coverage enforced
npm test          # just the tests

Runs exactly what CI runs, offline and without credentials: a syntax check, the protocol smoke test and the hygiene scan.

The smoke test completes the MCP handshake over stdio and asserts the things that have actually broken here — a server version drifting from package.json, a tool in the dispatcher but missing from the tool list (or advertised and unhandled), a required property absent from a schema, and descriptions too thin to choose a tool from. The hygiene scan refuses secrets, tracked session files and personal identifiers.

License

MIT © sapn95 — see LICENSE.