Which integrations are available for this server?

Integrates with Proton Calendar through ICS exports or refreshable Proton links to read an agenda and prepare calendar import files. Integrates with Proton Drive via the official Proton Drive CLI to list, inspect, download, and optionally upload files. Integrates with Proton Mail via Bridge or an authenticated read-only helper to read headers and messages, prepare drafts, and optionally send email.

How do I use waypost?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@waypost list my last 5 inbox emails and show this week's agenda" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

waypost

by baney75

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Waypost documentation for Mail, Drive, and Calendar

Agent tools for Proton Mail, Drive, and Calendar, shared by a CLI and an MCP server. Run it locally over stdio, or self-host it as a remote MCP that claude.ai, Claude Code and other agents share.

Built with TypeScript and Node.js.

Get started · Self-host · Add to an agent · Mail with Bridge · Setup · Proton support · Security

Service	Connection	What works
Mail	Proton Mail Bridge, or an authenticated read-only helper	List folders and labels, search and page headers, read messages and threads, save attachments, prepare drafts, optionally send, star, mark read, move and label, and explain what your Sieve filter does to a message.
Drive	Official Proton Drive CLI	List, inspect, download with a checksum check, optionally upload.
Calendar	An agent calendar Proton subscribes to, plus mirrored Proton share links and ICS exports	One merged view with provenance and an `editable` flag, agent-owned events agents can create and change, proposals for your own events, free/busy and conflicts, and import files.
Codes	Your Proton Mail, plus forwarded SMS on a Mac	Find the newest one-time sign-in code and fill it in the browser. Off until you turn it on.

Waypost is an independent project. Your Proton account password stays in Proton’s sign-in screens. Bridge and Drive keep separate sessions; Calendar imports need verification in the app. Read the supported routes and limits before connecting an account.

Get started

Requires Node.js 22.14+. You can explore the CLI and prepare calendar files before connecting any service.

git clone https://github.com/baney75/waypost.git
cd waypost
npm ci --ignore-scripts
npm run build
node dist/cli.js init
node dist/cli.js tools

Connect the services you need. Drive opens Proton’s own browser sign-in:

node dist/cli.js connect drive
node dist/cli.js connect calendar /absolute/path/to/calendar-export.ics

Self-hosting for claude.ai and several agents at once takes about 15 minutes with Docker and a free Cloudflare account. You don't need a domain: waypost setup cloudflare makes your own tunnel and a workers.dev address on your account. See Self-host. The rest of this page covers the local setup.

Mail uses Bridge’s public certificate and generated credentials, or an existing authenticated read-only helper. Calendar share links are read from a private file or a Proton Pass item and reused for 10 minutes; Proton may delay changes by up to eight hours. Follow Setup, then run:

node dist/cli.js doctor

Each service reports ready, not_configured, or failed. ready identifies the check that passed; a parsed Calendar snapshot does not prove live calendar access.

Related MCP server: Proton Safe MCP

Add to an agent

The bundled runtime needs only Node.js. From the waypost folder, register it with Claude Code for every project:

claude mcp add waypost --scope user -- node "$PWD/runtime/waypost.mjs" mcp
claude mcp list

claude mcp list should show waypost: ... ✔ Connected. In a session, ask Claude to run waypost_status. If you keep the config somewhere other than ~/.config/waypost/config.json, run node dist/cli.js --config /path/to/config.json agent-config claude-code and paste the command it prints.

For Claude Desktop, add this to claude_desktop_config.json (Settings, Developer, Edit Config) with the absolute path to your clone, then restart the app. node dist/cli.js agent-config claude prints the same entry.

{
  "mcpServers": {
    "waypost": {
      "command": "node",
      "args": ["/absolute/path/to/waypost/runtime/waypost.mjs", "mcp"]
    }
  }
}

Direct Bridge reads WAYPOST_MAIL_USERNAME and WAYPOST_MAIL_PASSWORD (or *_FILE paths to Docker secrets) from the environment of the process that starts Waypost. See Mail with Proton Bridge and Setup. waypost mcp uses standard input/output and opens no network listener; waypost serve is the opt-in remote mode.

For a remote Waypost, add it to Claude Code with claude mcp add --transport http waypost https://<your host>/mcp --scope user, or to claude.ai under Customize → Connectors → Add custom connector.

Tools

Tool	What it does
`waypost_status`	Which services are set up and which writes are allowed. Works before setup.
`mail_mailboxes`	Folder and label names (`Folders/…`, `Labels/…`, `All Mail`).
`mail_list`	Newest headers first; filter by `from`, `to`, `subject`, `text`, `unseen`, `since`, `before`; page with `beforeUid`.
`mail_read`	One message: text (HTML converted to text), threading IDs, attachment list. Long bodies page with `textOffset`. Never marks mail read.
`mail_thread`	Messages in the same conversation.
`mail_attachment`	Saves one attachment to the local artifacts folder.
`mail_draft`, `mail_send`	Prepare a local EML; sending is off by default and needs `confirm: true` per call.
`mail_verification_code`	Newest one-time code, never the body. Off by default.
`drive_list`, `drive_info`, `drive_download`, `drive_upload`	Drive under `/my-files`; uploads are off by default and need `confirm: true`.
`mail_flag`, `mail_mark`, `mail_move`, `mail_label`	Star, mark read, move to a folder, add a label. Off by default; each call needs `confirm: true`. No delete, no moves to Trash or Spam.
`mail_triage`	What your saved Proton Sieve filter would do to one message, and which rules matched.
`calendar_events`	Every calendar in one window: the agent calendar, mirrored Proton links and ICS files, each event with `provenance` and `editable`.
`calendar_create`, `calendar_update`, `calendar_delete`	Change agent-owned events in the Agents calendar. Off by default; each needs `confirm: true`.
`calendar_propose`, `calendar_cancel_invite`	For events you own in Proton: adopt into the agent calendar (default), prepare an invitation, or ask you to delete it.
`calendar_freebusy`	Busy intervals and overlapping events across all calendars.
`calendar_prepare`	Write an ICS file to import.
`pass_lookup`	Proton Pass item names and URLs only.

Errors come back as {ok:false, error:{code, message}}, and the message says what to run or change, for example MAIL_AUTH, MAIL_MAILBOX_NOT_FOUND, DRIVE_NOT_FOUND or CONFIG_MISSING.

Mail with Proton Bridge

Proton Mail Bridge is Proton's desktop app. It runs on your computer, decrypts your mailbox locally, and serves it on 127.0.0.1 over IMAP and SMTP. Proton Mail has no public mail API, so Waypost reads mail through Bridge. Bridge needs a paid Proton plan that includes Mail.

Install Bridge, sign in with your Proton account, and leave it running.
In Bridge, open your account and choose Configure email client (the account page that lists the hostname, IMAP and SMTP ports, username and password). Bridge generates this username and password for mail clients. Your Proton account password does not work here.
In Settings, Advanced settings, Export TLS certificates, export to a private folder. Give Waypost only the public certificate PEM, never the private key. Set Bridge's connection mode to STARTTLS.
Connect and check:

node dist/cli.js connect mail --certificate /absolute/path/to/bridge-certificate.pem
WAYPOST_MAIL_USERNAME="bridge-generated-username" \
WAYPOST_MAIL_PASSWORD="bridge-generated-password" \
  node dist/cli.js mail doctor

Those two values are placeholders. For daily use, supply them from a secret manager rather than typing them in a shell, for example pass-cli run --env-file bridge.references.env -- claude; Setup shows the pattern. The default ports are IMAP 1143 and SMTP 1025; use whatever Bridge shows.

Without Bridge, these still work:

Drive needs only Proton's official Drive CLI and its browser sign-in.
Calendar needs only an exported .ics file, or a Proton share link you create yourself. calendar_prepare writes import files with no connection at all.
waypost_status and waypost doctor run before any setup and report each service as ready, not_configured, or failed.

Mail is the only service that needs Bridge (or an existing read-only helper, see Setup).

Other agents

node dist/cli.js agent-config cursor and agent-config generic print entries for other MCP clients; the stdio entry above works in any client that launches a local command.

The Codex plugin bundles the runtime and a focused agent skill. Pin it to a release tag from the releases page, replacing <tag>:

codex plugin marketplace add baney75/waypost --ref <tag>
codex plugin add waypost@waypost

Service setup is still required after installing the plugin. The GitHub marketplace is separate from OpenAI's reviewed universal directory. Codex filters the environment it passes to MCP servers; see Setup for the Bridge variables.

Use the CLI

Install locally with npm install -g ., or replace waypost below with node runtime/waypost.mjs.

waypost drive list --path /my-files
waypost mail mailboxes
waypost mail list --subject invoice --since 2026-09-01 --limit 20
waypost mail read --uid 123
waypost calendar agenda --days 7 --timezone Europe/London
waypost call waypost_briefing --input '{"days":7,"mail":8}'   # events + newest mail in one call
waypost calendar prepare --summary "Project review" \
  --start 2026-10-05T09:00:00 --end 2026-10-05T09:30:00 --timezone Europe/London \
  --rrule "FREQ=WEEKLY;COUNT=4"
waypost calendar prepare --summary "Vacation" --start 2026-12-21 --end 2026-12-24 --all-day

Use normal flags for terminal work, or retain --input JSON for scripts. Repeat array flags such as --to for each recipient. Commands return JSON. waypost tools lists every input schema; waypost call <tool> --input '{}' addresses the same tools as MCP.

Every write starts disabled: mail sends, mail organizing, agent calendar writes and Drive uploads. When enabled in local config, each call must still pass confirm: true (--confirm on the CLI). Proton calendars are never written. A send also requires a prepared EML file and its exact SHA-256. Downloads use a new directory. Waypost exposes no permanent-delete or public-sharing tool.

Fill verification codes

Waypost can find the sign-in code a site just emailed you and fill it in the browser with one click. A small Chromium extension in extension/ talks to Waypost through the browser’s native messaging, so no port is opened. Codes are given only to the site whose domain matches the sender. It is off until you pair it. See Verification codes for setup on a Mac and the threat model.

Maintain

waypost update checks GitHub release metadata and never installs code. Updates explains version pinning, checksums, and rollback.

npm run verify

The tests use synthetic data. They drive the MCP server over stdio against a real IMAP server (pymap, pipx install pymap==0.36.7), and run the extension in Chromium when it is installed. Account-level checks require the configured official services. See Verification for the release’s observed coverage.

MIT · Privacy · Contributing