baney75/waypost

imageWaypost — Mail and files. Calendar handoffs.

imageWaypost documentation for Mail, Drive, and Calendar

Local tools for Proton Mail, Drive, and Calendar, shared by a CLI and an MCP server. Built for agents working on your computer.

Built with TypeScript and Node.js.

Get started · Setup · Proton support · Security

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

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.

Add to an agent

The bundled runtime needs Node.js and has no dependency-install step.

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

For Claude Code, register the bundled runtime once for every project:

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

For Claude Desktop or Cursor, run node dist/cli.js agent-config claude and paste the JSON into the client’s MCP settings. For Codex, run node dist/cli.js agent-config codex. With direct Bridge, the client must pass WAYPOST_MAIL_USERNAME and WAYPOST_MAIL_PASSWORD from your secret manager; never paste them into a config file. MCP uses standard input/output and opens no network listener.

The Codex plugin bundles the runtime and a focused agent skill. Install from the pinned release:

codex plugin marketplace add baney75/waypost --ref v0.3.0
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.

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 list --mailbox INBOX --limit 5
waypost calendar agenda --days 7
waypost calendar prepare --summary "Project review" \
  --start 2026-10-05T14:00:00Z --end 2026-10-05T14:30:00Z

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.

Mail and Calendar are read-only by default. Mail sends and Drive uploads start disabled; when enabled in local config, each call must still pass confirm: true (--confirm on the CLI). 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.

Maintain

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

npm run verify

The tests cover CLI/MCP negotiation, policy failures, file boundaries, mail transport, and calendar parsing using synthetic data. Account-level checks require the configured official services. See Verification for the release’s observed coverage.

MIT · Privacy · Contributing