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

1. Python 3.12+
2. uv — install with brew install uv (macOS) or see uv docs
3. 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.json Windows: %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": "alice@example.com,bob@example.com",
        "HIMALAYA_SEND_TIMEOUT": "15"
      }
    }
  }
}

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 APPROVED_RECIPIENTS=alice@example.com,bob@example.com himalaya -- uv run --project /path/to/himalaya-mcp-server himalaya-mcp-server

Modes

Environment Variables

Available Tools

Read-only tools (always available)

Write tools (full and dangerzone modes)

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

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.

Composing and sending emails

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

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

MML template format

From: you@example.com
To: recipient@example.com
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.

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