proton-mail-bridge-client 1.15.0 → 1.17.0

package/README.md

@@ -24,12 +24,12 @@
 
 ---
 
-Give Claude Desktop (or Cline, or any MCP client) full access to your Proton Mail inbox: read, search, send, draft, triage threads, manage folders, save attachments, and more. The same 40+ capabilities are also available as a full CLI for scripting, cron, and piped automation — no Claude required.
+Give Claude Desktop (or Cline, or any MCP client) full access to your Proton Mail inbox: read, search, send, draft, triage threads, manage folders, save attachments, and more — 78 MCP tools in total. Most of the same capabilities are also available as a full CLI for scripting, cron, and piped automation — no Claude required.
 
 ## What you get
 
 - **Claude reads and manages your Proton Mail** — triage, reply, draft, archive, search, move, batch-act on threads, pull attachments
-- **Full CLI** — same 40+ commands, scriptable and pipeable, works in cron and shell scripts
+- **Full CLI** — 73 commands covering nearly all of the same capabilities, scriptable and pipeable, works in cron and shell scripts
 - **Fast local search** — full-text search across your inbox without hitting IMAP on every query
 - **Safety controls** — read-only mode, send gate, destructive-action confirmation, per-action allowlist
 - **Privacy-native** — no third-party email service involved; your mail stays on your machine
@@ -194,6 +194,40 @@ The wizard handles config automatically. If you need to set it up by hand, three
 
 ---
 
+## Connect to Claude Code
+
+Install globally, then register the server with one command:
+
+```bash
+npm install -g proton-mail-bridge-client
+
+claude mcp add proton-mail-bridge \
+  -e PROTONMAIL_USERNAME=you@proton.me \
+  -e PROTONMAIL_PASSWORD=your-bridge-password \
+  -- proton-mail-bridge-mcp
+```
+
+`your-bridge-password` is the Bridge app's own password (**Bridge → account → Mailbox details**), not your Proton account password — see the note under [Prerequisites](#prerequisites).
+
+By default this registers the server for the current project only. Add `-s user` to make it available in every project:
+
+```bash
+claude mcp add proton-mail-bridge -s user \
+  -e PROTONMAIL_USERNAME=you@proton.me \
+  -e PROTONMAIL_PASSWORD=your-bridge-password \
+  -- proton-mail-bridge-mcp
+```
+
+Verify it's connected:
+
+```bash
+claude mcp list
+```
+
+For file-based or command-based credentials instead of plaintext env vars, add `-e PROTONMAIL_USERNAME_FILE=/path/to/file` (or `_COMMAND`) the same way — see the credential methods under [Manual config](#connect-to-claude-desktop) above.
+
+---
+
 ## Connect to Cline (VS Code)
 
 Install globally (`npm install -g proton-mail-bridge-client`), then open Cline's MCP settings:
@@ -247,6 +281,8 @@ Reload the Cline extension after saving. Proton Mail tools will appear in Cline'
 
 > **Tip:** When creating folders, use `Folders/Name` (not just `Name`) — that's the Proton Bridge namespace for real folders vs. labels.
 
+More recipes — expanded triage prompts, cron scripts for scheduled digests, and a Claude Code `/mail-triage` slash command — are in [examples/](examples/).
+
 ---
 
 ## Recommended System Prompt
@@ -268,144 +304,18 @@ Rules:
 
 ## CLI
 
-```bash
-proton-mail-bridge-client <command> [options]
-```
-
-All commands support `--json` for machine-readable output.
-
-### Read
-
-```bash
-proton-mail-bridge-client emails --folder INBOX --limit 25
-proton-mail-bridge-client read INBOX::25642
-proton-mail-bridge-client search "invoice" --limit 10
-proton-mail-bridge-client search --live --from openai.com
-proton-mail-bridge-client attachments INBOX::25642
-```
-
-### Triage
-
-```bash
-proton-mail-bridge-client digest
-proton-mail-bridge-client threads "quarterly review"
-proton-mail-bridge-client actionable
-proton-mail-bridge-client followups
-proton-mail-bridge-client thread-brief <threadId>
-proton-mail-bridge-client document-threads --category invoice
-proton-mail-bridge-client meeting-context alice@example.com
-```
-
-### Compose & send
-
-```bash
-proton-mail-bridge-client send --to bob@example.com --subject "Hey" --body "Hello"
-echo "Hello" | proton-mail-bridge-client send --to bob@example.com --subject "Hey"
-proton-mail-bridge-client reply INBOX::25642 --body "On it."
-proton-mail-bridge-client reply INBOX::25642 --reply-all --body "On it."
-proton-mail-bridge-client forward INBOX::25642 --to carol@example.com
-```
-
-### Mailbox actions
-
-```bash
-proton-mail-bridge-client move INBOX::25642 Folders/Archive
-proton-mail-bridge-client archive INBOX::25642
-proton-mail-bridge-client trash INBOX::25642
-proton-mail-bridge-client restore Trash::25642
-proton-mail-bridge-client mark-read INBOX::25642
-proton-mail-bridge-client mark-read INBOX::25642 --unread
-proton-mail-bridge-client star INBOX::25642
-proton-mail-bridge-client delete INBOX::25642
-proton-mail-bridge-client batch archive INBOX::100,INBOX::101,INBOX::102
-proton-mail-bridge-client thread-action <threadId> archive
-```
-
-### Folders
-
-```bash
-proton-mail-bridge-client folders
-proton-mail-bridge-client create-folder Folders/Receipts
-proton-mail-bridge-client rename-folder Folders/Receipts Folders/Bills
-proton-mail-bridge-client delete-folder Folders/Bills
-```
-
-### Drafts
-
-```bash
-proton-mail-bridge-client drafts
-proton-mail-bridge-client draft-create --to bob@example.com --subject "Draft" --body "..."
-proton-mail-bridge-client draft-read <id>
-proton-mail-bridge-client draft-update <id> --subject "Updated subject"
-proton-mail-bridge-client draft-reply INBOX::25642 --body "Will do."
-proton-mail-bridge-client draft-forward INBOX::25642 --to carol@example.com
-proton-mail-bridge-client draft-sync <id>
-proton-mail-bridge-client draft-send <id>
-proton-mail-bridge-client draft-delete <id>
-proton-mail-bridge-client remote-drafts
-```
-
-### Analytics & diagnostics
-
-```bash
-proton-mail-bridge-client stats
-proton-mail-bridge-client analytics
-proton-mail-bridge-client contacts
-proton-mail-bridge-client volume-trends --days 14
-proton-mail-bridge-client watch --timeout 30
-proton-mail-bridge-client test-email you@example.com
-proton-mail-bridge-client doctor
-proton-mail-bridge-client status
-proton-mail-bridge-client sync --folder INBOX --limit 150
-```
-
-### Ambient notifications
-
-Run as a background daemon — sends a system notification (macOS / Linux) whenever new mail arrives:
-
-```bash
-proton-mail-bridge-client notify                              # foreground (Ctrl+C to stop)
-proton-mail-bridge-client notify &                            # background
-proton-mail-bridge-client notify --folder INBOX --timeout 60  # custom folder and idle timeout
-```
-
-Each event is also written as a JSON line to stdout:
-
-```json
-{"event":"new_mail","folder":"INBOX","count":2,"at":"2026-05-18T14:32:01.000Z"}
-```
-
-Uses IMAP IDLE — no polling between events. Reconnects automatically on transient errors.
-
-### MCP tool passthrough
-
-Any MCP tool is also callable directly from the CLI:
+Every capability is also a scriptable terminal command — no Claude required:
 
 ```bash
-proton-mail-bridge-client tools
-proton-mail-bridge-client tool get_connection_status --json
-proton-mail-bridge-client tool search_indexed_emails --args '{"query":"invoice","limit":3}'
+proton-mail-bridge-client digest                                    # morning triage summary
+proton-mail-bridge-client search --from stripe.com --json | jq .    # scriptable search
+echo "Deploy done" | proton-mail-bridge-client send --to you@x.com --subject "Deploy"
+proton-mail-bridge-client notify &                                  # background new-mail alerts
 ```
 
-### Pipe and script
-
-```bash
-# Morning digest to a file
-proton-mail-bridge-client digest --json > ~/morning-mail.json
+All commands support `--json` for machine-readable output, and any MCP tool is directly callable via `proton-mail-bridge-client tool <name> --args '{...}'`.
 
-# Pull every email from a domain
-proton-mail-bridge-client search --from stripe.com --json | jq '.[].subject'
-
-# Pipe a script's output directly into an email
-echo "Deploy complete on $(hostname) at $(date)" \
-  | proton-mail-bridge-client send --to alerts@example.com --subject "Deploy done"
-
-# Scheduled digest every weekday at 8am (cron)
-0 8 * * 1-5 proton-mail-bridge-client digest >> ~/mail-log.txt
-
-# Count unread in INBOX
-proton-mail-bridge-client emails --folder INBOX --json | jq '[.[] | select(.isRead == false)] | length'
-```
+**Full command reference: [docs/cli.md](docs/cli.md)** (73 commands across read, triage, compose, mailbox actions, folders, drafts, analytics, and diagnostics).
 
 ---
 
@@ -447,7 +357,7 @@ PROTONMAIL_PASSWORD_COMMAND='pass proton/password'
 PROTONMAIL_DATA_DIR="$HOME/.proton-mail-bridge-client"
 
 # Tools
-PROTONMAIL_TOOL_TIER='full'          # 'core' exposes 20 essential tools (saves context window); 'full' exposes all 76
+PROTONMAIL_TOOL_TIER='full'          # 'core' exposes 20 essential tools (saves context window); 'full' exposes all 93
 
 # Safety
 PROTONMAIL_READ_ONLY='false'
@@ -455,6 +365,8 @@ PROTONMAIL_ALLOW_SEND='true'
 PROTONMAIL_ALLOW_REMOTE_DRAFT_SYNC='true'
 PROTONMAIL_ALLOWED_ACTIONS='mark_read,mark_unread,star,unstar,archive,trash,restore'
 PROTONMAIL_CONFIRM_DESTRUCTIVE='false'
+PROTONMAIL_SEND_DELAY_SECONDS='0'    # >0: send_email queues instead of sending immediately, cancelable via cancel_send. Only fires while this server stays running.
+PROTONMAIL_SIGNATURE=''              # Plain text, appended to send_email bodies (text + HTML). Opt out per-message with appendSignature: false.
 
 # Sync
 PROTONMAIL_AUTO_SYNC='true'
@@ -500,7 +412,7 @@ PROTONMAIL_IDLE_MAX_SECONDS='30'
 `mark_email_read` · `star_email` · `move_email` · `archive_email` · `trash_email` · `restore_email` · `delete_email` · `batch_email_action` · `apply_thread_action` · `empty_folder` · `bulk_delete` · `bulk_move` · `bulk_update_flags` · `bulk_update_labels` · `update_message_flags` · `update_message_labels`
 
 ### Folder management
-`create_folder` · `rename_folder` · `delete_folder` · `create_label`
+`create_folder` · `rename_folder` · `delete_folder` · `create_label` · `rename_label` · `delete_label`
 
 ### Analytics
 `get_email_stats` · `get_email_analytics` · `get_contacts` · `get_volume_trends` · `folder_stats` · `top_senders`

package/dist/cli.d.ts

@@ -7,6 +7,13 @@ export interface ParsedCliArgs {
     flags: CliFlags;
 }
 export declare function parseCliArgs(argv: string[]): ParsedCliArgs;
+interface ToolOnlyCommand {
+    command: string;
+    tool: string;
+    positionals: string[];
+    help: string;
+}
+export declare const TOOL_ONLY_COMMANDS: ToolOnlyCommand[];
 export declare function main(): Promise<void>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA4BA,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAgC1D;AAilDD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAmN1C"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA4BA,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAgC1D;AAskDD,UAAU,eAAe;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,kBAAkB,EAAE,eAAe,EA4D/C,CAAC;AA0CF,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAyN1C"}

package/dist/cli.js

@@ -126,6 +126,10 @@ function printHelp() {
         "  draft-thread-reply <id> Create a reply draft for a thread",
         "  tools                  List every MCP tool exposed by the server",
         "  tool <name>            Call any MCP tool with JSON arguments",
+        "",
+        "Additional 1:1 tool commands (required args positional, rest via --args):",
+        ...TOOL_ONLY_COMMANDS.map((entry) => `  ${entry.command.padEnd(23)} ${entry.help}`),
+        "",
         "  claude setup           Run the interactive Claude Desktop setup wizard",
         "  claude install         Install or update the Claude Desktop runtime",
         "  claude check           Check Claude Desktop integration status",
@@ -1545,6 +1549,83 @@ async function runTool(parsed) {
         printToolCallResult(result, wantJson);
     });
 }
+export const TOOL_ONLY_COMMANDS = [
+    { command: "cancel-send", tool: "cancel_send", positionals: ["id"], help: "Cancel a send queued by PROTONMAIL_SEND_DELAY_SECONDS" },
+    { command: "unsubscribe-info", tool: "get_unsubscribe_info", positionals: ["emailId"], help: "Read List-Unsubscribe details for a message" },
+    { command: "unsubscribe-sender", tool: "unsubscribe_sender", positionals: ["emailId"], help: "Execute a mailto unsubscribe (--args '{\"confirmed\":true}' if required)" },
+    { command: "reply-to-email", tool: "reply_to_email", positionals: ["emailId", "body"], help: "Immediately send a reply (full tool: attachments/dryRun via --args)" },
+    { command: "reply-all-email", tool: "reply_all_email", positionals: ["emailId"], help: "Immediately reply to all recipients (--args '{\"body\":...}')" },
+    { command: "forward-email", tool: "forward_email", positionals: ["emailId", "to"], help: "Immediately forward a message, preserving attachments" },
+    { command: "list-drafts", tool: "list_drafts", positionals: [], help: "List local drafts (tool form; see also `drafts`)" },
+    { command: "schedule-draft", tool: "schedule_draft", positionals: ["draftId", "sendAt"], help: "Queue a saved draft to send at a future time" },
+    { command: "get-email-by-id", tool: "get_email_by_id", positionals: ["emailId"], help: "Fetch one email (tool form; see also `read`)" },
+    { command: "get-emails-by-ids", tool: "get_emails_by_ids", positionals: ["emailIds"], help: "Fetch up to 25 emails by comma-separated ids" },
+    { command: "search-emails", tool: "search_emails", positionals: [], help: "Live IMAP search (tool form; see also `search --live`)" },
+    { command: "get-folders", tool: "get_folders", positionals: [], help: "List folders (tool form; see also `folders`)" },
+    { command: "sync-folders", tool: "sync_folders", positionals: [], help: "Refresh the in-memory folder list from IMAP" },
+    { command: "mark-email-read", tool: "mark_email_read", positionals: ["emailId"], help: "Mark read/unread (tool form; see also `mark-read`)" },
+    { command: "star-email", tool: "star_email", positionals: ["emailId"], help: "Star/unstar (tool form; see also `star`)" },
+    { command: "move-email", tool: "move_email", positionals: ["emailId", "targetFolder"], help: "Move an email (tool form; see also `move`)" },
+    { command: "archive-email", tool: "archive_email", positionals: ["emailId"], help: "Archive an email (tool form; see also `archive`)" },
+    { command: "trash-email", tool: "trash_email", positionals: ["emailId"], help: "Move to Trash (tool form; see also `trash`)" },
+    { command: "restore-email", tool: "restore_email", positionals: ["emailId"], help: "Restore from Trash (tool form; see also `restore`)" },
+    { command: "snooze-email", tool: "snooze_email", positionals: ["emailId", "wakeAt"], help: "Snooze a message until wakeAt (ISO timestamp)" },
+    { command: "cancel-snooze", tool: "cancel_snooze", positionals: ["id"], help: "Wake a snoozed email immediately" },
+    { command: "create-template", tool: "create_template", positionals: ["name", "subject", "body"], help: "Save a reusable email template" },
+    { command: "list-templates", tool: "list_templates", positionals: [], help: "List saved email templates" },
+    { command: "get-template", tool: "get_template", positionals: ["id"], help: "Get a saved template by id" },
+    { command: "delete-template", tool: "delete_template", positionals: ["id"], help: "Delete a saved template" },
+    { command: "render-template", tool: "render_template", positionals: ["id"], help: "Render a template ({{var}} substitution via --args '{\"variables\":{...}}')" },
+    { command: "delete-email", tool: "delete_email", positionals: ["emailId"], help: "Permanently delete (tool form; see also `delete`)" },
+    { command: "update-message-labels", tool: "update_message_labels", positionals: ["emailId"], help: "Add/remove Proton labels on one message" },
+    { command: "update-message-flags", tool: "update_message_flags", positionals: ["emailId"], help: "Add/remove IMAP flags on one message" },
+    { command: "count-messages", tool: "count_messages", positionals: [], help: "Count messages matching live IMAP search criteria" },
+    { command: "bulk-update-flags", tool: "bulk_update_flags", positionals: [], help: "Add/remove IMAP flags on multiple messages" },
+    { command: "bulk-update-labels", tool: "bulk_update_labels", positionals: [], help: "Add/remove Proton labels on multiple messages" },
+    { command: "top-senders", tool: "top_senders", positionals: [], help: "Top senders in a folder over a date range" },
+    { command: "move-thread", tool: "move_thread", positionals: ["messageId", "destination"], help: "Move every message in a thread" },
+    { command: "delete-thread", tool: "delete_thread", positionals: ["messageId"], help: "Delete every message in a thread" },
+    { command: "flag-thread", tool: "flag_thread", positionals: ["messageId"], help: "Add/remove IMAP flags across a thread" },
+    { command: "create-label", tool: "create_label", positionals: ["name"], help: "Create a Proton label" },
+    { command: "rename-label", tool: "rename_label", positionals: ["name", "newName"], help: "Rename a Proton label" },
+    { command: "delete-label", tool: "delete_label", positionals: ["name"], help: "Delete a Proton label" },
+    { command: "get-connection-status", tool: "get_connection_status", positionals: [], help: "(tool form; see also `connection-status`)" },
+    { command: "get-runtime-status", tool: "get_runtime_status", positionals: [], help: "(tool form; see also `runtime-status`)" },
+    { command: "run-doctor", tool: "run_doctor", positionals: [], help: "Full production health check (tool form; see also `doctor`)" },
+    { command: "run-background-sync", tool: "run_background_sync", positionals: [], help: "Trigger the configured background sync cycle now" },
+    { command: "sync-emails", tool: "sync_emails", positionals: [], help: "(tool form; see also `sync`)" },
+    { command: "get-index-status", tool: "get_index_status", positionals: [], help: "(tool form; see also `index-status`)" },
+    { command: "search-indexed-emails", tool: "search_indexed_emails", positionals: [], help: "(tool form; see also `search`)" },
+    { command: "get-labels", tool: "get_labels", positionals: [], help: "(tool form; see also `labels`)" },
+    { command: "get-threads", tool: "get_threads", positionals: [], help: "(tool form; see also `threads`)" },
+    { command: "get-inbox-digest", tool: "get_inbox_digest", positionals: [], help: "(tool form; see also `digest`)" },
+    { command: "get-follow-up-candidates", tool: "get_follow_up_candidates", positionals: [], help: "(tool form; see also `followups`)" },
+    { command: "list-attachments", tool: "list_attachments", positionals: ["emailId"], help: "(tool form; see also `attachments`)" },
+    { command: "get-attachment-content", tool: "get_attachment_content", positionals: ["emailId", "attachmentId"], help: "Fetch attachment metadata/base64" },
+    { command: "get-attachment-text", tool: "get_attachment_text", positionals: ["emailId", "attachmentId"], help: "Extract text from a text-like attachment" },
+    { command: "save-attachments", tool: "save_attachments", positionals: ["emailId"], help: "Save all attachments from an email to disk" },
+    { command: "save-attachment", tool: "save_attachment", positionals: ["emailId", "attachmentId"], help: "Save one attachment to disk" },
+    { command: "export-email", tool: "export_email", positionals: ["emailId"], help: "Save raw .eml source to disk" },
+    { command: "import-email", tool: "import_email", positionals: ["raw"], help: "Import a raw .eml message via IMAP APPEND" },
+    { command: "clear-index", tool: "clear_index", positionals: [], help: "Delete the local SQLite mailbox index" },
+    { command: "get-audit-logs", tool: "get_audit_logs", positionals: [], help: "Recent write-operation audit log entries" },
+];
+async function runToolOnlyCommand(entry, parsed) {
+    const wantJson = isTruthyFlag(parsed.flags.json);
+    const args = {};
+    entry.positionals.forEach((field, index) => {
+        const value = parsed.positionals[index];
+        if (value === undefined) {
+            throw new Error(`${entry.command} requires: ${entry.positionals.join(", ")}`);
+        }
+        args[field] = value;
+    });
+    Object.assign(args, (await parseToolArgs(parsed)) ?? {});
+    await withMcpClient(async (client) => {
+        const result = await client.callTool({ name: entry.tool, arguments: args });
+        printToolCallResult(result, wantJson);
+    });
+}
 async function runClaude(parsed) {
     switch (parsed.subcommand) {
         case "setup":
@@ -1772,8 +1853,14 @@ export async function main() {
         case "claude":
             await runClaude(parsed);
             return;
-        default:
+        default: {
+            const toolOnly = TOOL_ONLY_COMMANDS.find((entry) => entry.command === parsed.command);
+            if (toolOnly) {
+                await runToolOnlyCommand(toolOnly, parsed);
+                return;
+            }
             throw new Error(`Unknown command: ${parsed.command}`);
+        }
     }
 }
 const isDirectExecution = isMainModule(import.meta.url);