himalaya-mcp-server

MCP server that exposes email operations to AI agents (Claude Cowork, Claude Code, etc.) via the himalaya CLI.

Read-only by default. Write and send operations must be explicitly enabled.

Features

Broad himalaya coverage: accounts, folders, envelopes, messages, flags, attachments, templates
Three modes: read-only (safe default), full (write operations), and dangerzone (sending emails)
No destructive operations: delete, purge, and expunge commands are deliberately excluded (see Excluded Commands)
Security-first: write tools labeled [DANGER: WRITE], send tools labeled [DANGERZONE: SENDS EMAIL]
No shell injection: all CLI calls use subprocess.run() with list arguments
Stdio transport: works natively with Claude Desktop / Cowork via claude_desktop_config.json

Prerequisites

Python 3.12+
uv — install with brew install uv (macOS) or see uv docs
himalaya — installed and configured with at least one email account

Verify himalaya is working:

himalaya account list

Installation

Clone the repository:

git clone https://github.com/andasv/himalaya-mcp-server.git
cd himalaya-mcp-server
uv sync

Usage with Claude Cowork / Claude Desktop

Add the server to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json

Read-only mode (default, recommended)

{
  "mcpServers": {
    "himalaya": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/himalaya-mcp-server", "himalaya-mcp-server"]
    }
  }
}

Full mode (enables move, copy, flag, and other write operations)

Warning: Full mode allows the AI agent to move messages, modify flags, create folders, and save drafts. It does not allow sending emails.

{
  "mcpServers": {
    "himalaya": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/himalaya-mcp-server", "himalaya-mcp-server"],
      "env": {
        "HIMALAYA_MODE": "full"
      }
    }
  }
}

Dangerzone mode (enables sending emails)

Warning: Dangerzone mode allows the AI agent to send real emails to real recipients. This is irreversible. Only enable this if you fully understand the risks.

Dangerzone mode requires the APPROVED_RECIPIENTS environment variable — a comma-separated list of email addresses the AI is allowed to send to. Sending to any other address will be blocked with a friendly error.

{
  "mcpServers": {
    "himalaya": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/himalaya-mcp-server", "himalaya-mcp-server"],
      "env": {
        "HIMALAYA_MODE": "dangerzone",
        "APPROVED_RECIPIENTS": "[email protected],[email protected]"
      }
    }
  }
}

After editing the config, restart Claude Desktop for changes to take effect.

Usage with Claude Code

# Read-only (default)
claude mcp add himalaya -- uv run --project /path/to/himalaya-mcp-server himalaya-mcp-server

# Full mode (write operations, no sending)
claude mcp add --env HIMALAYA_MODE=full himalaya -- uv run --project /path/to/himalaya-mcp-server himalaya-mcp-server

# Dangerzone mode (write + send, with approved recipients)
claude mcp add --env HIMALAYA_MODE=dangerzone --env [email protected],[email protected] himalaya -- uv run --project /path/to/himalaya-mcp-server himalaya-mcp-server

Modes

Mode	Env var	Tools available
readonly (default)	`HIMALAYA_MODE=readonly` or unset	List accounts/folders/envelopes, read messages, download attachments, generate templates
full	`HIMALAYA_MODE=full`	All of the above + move, copy, flag, create folders, save drafts
dangerzone	`HIMALAYA_MODE=dangerzone`	All of the above + send emails

Available Tools

Read-only tools (always available)

Tool	Description
`account_list`	List configured email accounts
`folder_list`	List folders/mailboxes
`envelope_list`	List message envelopes with search/filter/pagination
`envelope_thread`	Get thread view of envelopes
`message_read`	Read a message body by ID
`message_thread`	Read a full message thread
`attachment_download`	Download attachments from a message
`template_write`	Generate a blank email template (MML)
`template_reply`	Generate a reply template
`template_forward`	Generate a forward template

Write tools (full and dangerzone modes)

These tools are prefixed with [DANGER: WRITE] in their descriptions so the AI agent clearly sees the risk.

Tool	Description
`folder_create`	Create a new folder
`message_copy`	Copy a message to another folder
`message_move`	Move a message to another folder
`message_save`	Save a raw MIME message to a folder
`flag_add`	Add flags to a message
`flag_set`	Replace all flags on a message
`flag_remove`	Remove flags from a message
`template_save`	Compile MML template and save to folder

Send tools (dangerzone mode only)

These tools are prefixed with [DANGERZONE: SENDS EMAIL] in their descriptions. They send real emails to real recipients and cannot be undone.

Tool	Description
`message_send`	Send a raw MIME message
`template_send`	Compile MML template and send email

Composing and sending emails

Since himalaya's interactive editor commands can't be used in an MCP context, email composition uses the template pipeline:

Generate a template with template_write, template_reply, or template_forward
Edit the template (the AI fills in To, Subject, body, etc.)
Send with template_send (requires dangerzone mode) or save as draft with template_save (requires full mode)

MML template format

From: [email protected]
To: [email protected]
Subject: Hello

Your message body here.

Excluded Commands

The following himalaya commands are deliberately not exposed through this MCP server for safety reasons. Allowing an AI agent to permanently delete emails or folders carries too high a risk of irreversible data loss.

himalaya command	What it does	Why it's excluded
`folder expunge`	Permanently removes messages marked for deletion	Irreversible bulk deletion
`folder purge`	Deletes ALL messages in a folder	Irreversible bulk deletion
`folder delete`	Deletes an entire folder and its contents	Irreversible data loss
`message delete`	Permanently deletes a single message	Irreversible data loss

If you need these operations, use the himalaya CLI directly.

Security

Read-only by default — no write tools are even registered unless HIMALAYA_MODE=full or dangerzone
Sending requires dangerzone — email send tools are isolated in their own mode, separate from other write operations
Recipient allowlist — in dangerzone mode, APPROVED_RECIPIENTS must be set; emails can only be sent to explicitly approved addresses
No destructive operations — delete, purge, and expunge commands are excluded entirely
Danger labels — write tools show [DANGER: WRITE], send tools show [DANGERZONE: SENDS EMAIL]
No shell injection — all subprocess calls use list arguments, never shell=True
Input validation — all parameters are validated before being passed to the CLI
Subprocess timeouts — all CLI calls have a 30-second timeout to prevent hangs
himalaya handles auth — this server never touches credentials; himalaya manages its own auth via its config

License

MIT

himalaya-mcp-server