A privacy-first email assistant that wraps the himalaya CLI to let Claude read, search, organize, compose, and act on email across multiple accounts.
List & search mail: list_emails (paginated), search_emails with himalaya filter syntax (from, subject, after, flags, order by), list_starred, and get_unread_count.
Read messages: read_email (plain text), read_email_html, render_email (HTML→markdown), and read_email_raw (full MIME/.eml).
Organize: flag_email (add/remove Seen/Flagged/Answered/Draft), move_email between folders, and manage folders with list_folders, create_folder, delete_folder (confirm-gated).
Compose & send safely: compose_email and send_email return a preview unless confirm=true; compose_email can also save drafts; draft_reply generates reply templates (with reply_all).
Threads: list_threads groups conversations by subject and read_thread returns all messages chronologically.
Attachments & calendar: list_attachments, download_attachment, extract_calendar_event (parses ICS invites), and create_calendar_event (macOS, confirm-gated).
Productivity extras: create_action_item (extract todos/deadlines), create_reminder (Apple Reminders), snooze_email / list_snoozed_emails, export_to_markdown, and copy_to_clipboard.
Diagnostics & multi-account: health_check tests per-account IMAP connectivity, and nearly every tool accepts an account parameter for per-call account switching.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@himalaya-mcp Show my latest 5 emails in inbox"
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.
Privacy-first email for Claude -- MCP server and Claude Code plugin (himalaya) wrapping the himalaya CLI.
29 MCP tools: list, search, read, flag, move, compose, draft reply, send (with safety gate), export, action items, clipboard, folders, attachments, calendar, threads, health check, get_unread_count, read_email_raw, render_email, list_starred, create_reminder, snooze_email, list_snoozed_emails
7 MCP prompts: triage inbox, summarize email, daily digest, weekly digest, draft reply, morning briefing, inbox check
3 MCP resources: inbox, message by ID, folders
16 plugin skills: /himalaya:inbox, /himalaya:triage, /himalaya:digest, /himalaya:reply, /himalaya:compose, /himalaya:attachments, /himalaya:search, /himalaya:manage, /himalaya:stats, /himalaya:config, /himalaya:help, /himalaya:morning, /himalaya:forward, /himalaya:export, /himalaya:threads, /himalaya:respond
Multi-account: per-call account switching via --account
Reliability: account-aware diagnostics via the health_check tool and multi-account doctor; structured error envelopes with one-line fix hints
Safe subprocess: uses execFile (no shell injection)
Two-phase send: send_email returns preview first, requires explicit confirm=true
Env-based config: HIMALAYA_BINARY, HIMALAYA_ACCOUNT, HIMALAYA_FOLDER, HIMALAYA_TIMEOUT
Related MCP server: io.github.p-w-4-z/inbox-mcp
brew tap data-wise/tap
brew install himalaya-mcpInstalls himalaya CLI + Node.js as dependencies, auto-symlinks plugin to ~/.claude/plugins/.
himalaya-mcp doctor # Verify installationPrerequisites: Node.js 22+ and himalaya CLI must be installed separately (brew install node himalaya).
claude plugin marketplace add Data-Wise/himalaya-mcp
claude plugin install himalayahimalaya-mcp doctor # Verify installationDownload himalaya-mcp-v{version}.mcpb from GitHub Releases and open it in Claude Desktop. Requires brew install himalaya separately -- the .mcpb does not bundle the himalaya CLI.
himalaya-mcp setupnpm install
npm run build
ln -s ~/projects/dev-tools/himalaya-mcp ~/.claude/plugins/himalaya-mcphimalaya-mcp doctor # Verify installationhimalaya CLI configured with at least one email account in ~/.config/himalaya/config.toml
Node.js 22+ (installed automatically by Homebrew)
npm test # 804 tests across 48 files (vitest)Category | Tests | Coverage |
Unit (parser, client, config, clipboard) | 41 | Core parsing, config, template variable guards |
Integration (tools, prompts) | 85 | Tool registration, MCP prompts, account validation |
Reliability (errors, retry, accounts, health) | 33 | Error envelope, transient retry, multi-account discovery, health_check |
v1.5.0 features | 79 | Threads (30), morning/inbox prompts (13), E2E integration (36) |
Dogfooding | 162 | Realistic Claude usage + reliability scenarios + .mcpb validation |
E2E | 39 | Full MCP server pipeline + structured envelope round-trip + .mcpb build pipeline |
Setup CLI | 45 | Setup, install/upgrade E2E, multi-account doctor, plugin structure, --help/--version |
Full documentation at data-wise.github.io/himalaya-mcp
The CLI ships with groff man pages following the flow-cli standard:
# After brew install himalaya-mcp, man pages are auto-installed to /opt/homebrew/share/man
man himalaya-mcp
man himalaya-mcp-doctor
man himalaya-mcp-setup
man himalaya-mcp-install-ext
man himalaya-mcp-remove-ext
# Or from the source repo:
MANPATH=$(pwd)/man man himalaya-mcpIf an email tool fails, ask Claude:
Run a health check on my email accounts.This invokes the health_check MCP tool and surfaces a per-account status with one-line fix hints.
From a terminal, run:
himalaya-mcp doctor # All accounts
himalaya-mcp doctor --account <name> # Single accountFor the full failure-mode catalog and recovery steps, see docs/troubleshooting.md.
MIT
Compose and send a new email (not a reply). SAFETY: requires confirm=true to actually send. Without confirm, returns a preview for user review. With save_draft=true, saves the message (attachments included) to the drafts mailbox instead of sending: no confirm needed, nothing is sent (requires himalaya v2).
Inputs: to (required), body (required), subject (required), cc, +6 more.
Copy text to the system clipboard (pbcopy on macOS, xclip on Linux). Useful for copying email content, markdown exports, or any text.
Inputs: text (required).
Read an email and extract action items, todos, deadlines, and commitments. Returns structured action items that can be used to create tasks, reminders, or calendar events.
Inputs: id (required), folder, account, destination.
Create an event in Apple Calendar. SAFETY: requires confirm=true to actually create. Without confirm, returns a preview. macOS only.
Inputs: dtend (required), dtstart (required), summary (required), confirm, +2 more.
Create a new email folder/mailbox.
Inputs: name (required), account.
Create a reminder in Apple Reminders (macOS only). Use for action items, follow-ups, and tasks extracted from email.
Inputs: title (required), notes, dueDate, priority.
Delete an email folder/mailbox. SAFETY: requires confirm=true to actually delete. Without confirm, returns a preview warning.
Inputs: name (required), account, confirm.
Download an email attachment to a temporary directory. Downloads all attachments, then returns the path to the requested file.
Inputs: id (required), filename (required), folder, account.
Generate a reply draft for an email. Returns the reply template with headers and quoted original message. Does NOT send — use send_email to send after user reviews.
Inputs: id (required), body, folder, account, +1 more.
Export an email as formatted markdown with YAML frontmatter (date, from, to, subject, flags). Returns the markdown text — you can then save it to a file or clipboard.
Inputs: id (required), folder, account.
Extract calendar event details from an email's ICS attachment. Downloads all attachments, finds the .ics file, parses it, and returns event summary, dates, location, and organizer.
Inputs: id (required), folder, account.
Add or remove flags on an email. Flags: Seen, Flagged, Answered, Draft (and Deleted on himalaya v1 only; on v2 delete by moving to the trash with move_email). Use 'add' to set flags, 'remove' to clear them.
Inputs: id (required), flags (required), action (required), folder, +1 more.
Get the number of unread emails in a folder (or across all folders). Uses himalaya's server-side filter for fast counting even in large mailboxes.
Inputs: folder, account.
Check himalaya-mcp installation health and per-account IMAP connectivity (folder + envelope surfaces). Use when an email tool fails to diagnose which accounts are reachable.
Inputs: account.
List attachments for an email message. Downloads all attachments to inspect them, then returns filename, MIME type (inferred from extension), and size for each.
Inputs: id (required), folder, account.
List emails in a folder. Returns envelope data: subject, from, date, flags.
Inputs: page, folder, account, page_size.
List all email folders/mailboxes for an account. Returns folder names.
Inputs: account.
List all snoozed emails and their unsnooze times. Emails past their snooze time are returned as expired and can be revisited.
Inputs: no named parameters.
List all flagged/starred emails. Returns envelopes with flag, subject, sender, and date. Uses server-side filtering for fast results.
Inputs: folder, account.
List email threads (conversations) in a folder. Groups related emails by subject line. Returns threads sorted by most recent activity, with participant list and message count.
Inputs: page, folder, account, page_size.
Move an email to a different folder. Common targets: Archive, Trash, Spam, Sent, Drafts.
Inputs: id (required), target_folder (required), folder, account.
Read an email message body (plain text). Use the ID from list_emails or search_emails.
Inputs: id (required), folder, account.
Read an email message body as HTML. Useful for formatted emails.
Inputs: id (required), folder, account.
Read the raw MIME source of an email. Returns the full, unedited message including all headers. Useful for debugging, email forensics, and exporting to .eml format.
Inputs: id (required), folder, account.
Read all messages in a conversation thread. Given a thread_id (the ID of the first message), fetches all related messages and returns them in chronological order. Use list_threads first to get thread IDs.
Inputs: thread_id (required), folder, account.
Read an email body rendered as clean markdown. For HTML emails, converts to markdown for a clean reading experience. For plain text emails, returns the body as-is.
Inputs: id (required), folder, account.
Search emails using himalaya filter syntax. Combine conditions with and/or (REQUIRED between every condition pair — omitting them causes parse errors). Negate any condition with not. Multi-word values: quote them or backslash-escape the spaces. Sort results with order by <date|from|to|subject> <asc|desc>. Conditions: subject, from, to, body, date (exact day), after (strictly after), flag. Flag values: seen, answered, flagged, draft, deleted. On himalaya v2 every word must belong to a condition (no bare words: use subject <word>), and there is no before: use not after <date>.
Inputs: query (required), folder, account.
Send an email template. SAFETY: requires confirm=true to actually send. Without confirm, returns a preview. Always show the user the preview and get their approval before sending with confirm=true.
Inputs: template (required), account, confirm, attachments.
Snooze an email until a specified time. The email will reappear in your inbox check after the snooze period expires.
Inputs: id (required), snoozeUntil (required), folder, account, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 29 tools
Most tools are clearly differentiated by resource and action, such as list_emails vs search_emails vs list_threads. However, the four email-reading variants (read_email, read_email_html, render_email, read_email_raw) and the draft/send/compose tools have some overlap that could cause misselection. Descriptions provide enough guidance to resolve most ambiguity.
Nearly all tools follow a predictable verb_noun pattern: list_emails, read_email, create_folder, delete_folder, send_email, move_email, etc. Minor deviations like export_to_markdown and health_check do not significantly disrupt readability. The convention is consistent enough for an agent to infer behavior.
The server exposes 29 tools, which exceeds the reasonable range for a focused email MCP surface. While many tools are useful, the count includes overlapping read variants, specialized extras, and unrelated utilities like clipboard and Apple Calendar/Reminders. This feels heavy and increases the chance of tool-selection confusion.
The surface covers the core email lifecycle well: search, read, flag, move, compose, send, folders, threads, attachments, and diagnostics. Minor gaps exist, such as explicit forward support and editing existing drafts, but agents can work around these. Overall the tool set is fairly complete for the stated himalaya email domain.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Email inboxes for AI agents: send, receive, reply, search, and manage threaded email over MCP.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Programmable email inbox for AI agents — JMAP, PoW auth, stdio MCP server.
