himalaya-mcp

himalaya-mcp

Privacy-first email for Claude -- MCP server and Claude Code plugin (email) wrapping the himalaya CLI.

Features

• 22 MCP tools: list, search, read, flag, move, compose, draft reply, send (with safety gate), export, action items, clipboard, folders, attachments, calendar, threads, health check
• 6 MCP prompts: triage inbox, summarize email, daily digest, draft reply, morning briefing, inbox check
• 3 MCP resources: inbox, message by ID, folders
• 12 plugin skills: /email:inbox, /email:triage, /email:digest, /email:reply, /email:compose, /email:attachments, /email:search, /email:manage, /email:stats, /email:config, /email:help, /email:morning
• 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

Install

Homebrew (recommended)

brew tap data-wise/tap
brew install himalaya-mcp

Installs himalaya CLI + Node.js as dependencies, auto-symlinks plugin to ~/.claude/plugins/.

himalaya-mcp doctor    # Verify installation

Claude Code Plugin (from GitHub)

Prerequisites: 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 email

himalaya-mcp doctor    # Verify installation

Claude Desktop (.mcpb -- one-click install)

Download 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.

Claude Desktop (CLI setup)

himalaya-mcp setup

Development (from source)

npm install
npm run build
ln -s ~/projects/dev-tools/himalaya-mcp ~/.claude/plugins/himalaya-mcp

himalaya-mcp doctor    # Verify installation

Prerequisites

• himalaya CLI configured with at least one email account in ~/.config/himalaya/config.toml
• Node.js 22+ (installed automatically by Homebrew)

Testing

npm test              # 484 tests across 23 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

Documentation

Full documentation at data-wise.github.io/himalaya-mcp

• Installation
• Quick Start
• Tutorials
• User Guide
• Command Reference
• Quick Reference Card
• Architecture

Troubleshooting

If 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 account

For the full failure-mode catalog and recovery steps, see docs/troubleshooting.md.

License

MIT