adguard-mail-mcp

MCP server for AdGuard Mail — manage email aliases, recipients, and temporary mailboxes through AI assistants (Claude, Cursor, Antigravity, etc.)

Install

npm install -g adguard-mail-mcp

Setup

1. Login to AdGuard Mail (one-time)

agm login

Important: The agm command is only available after global install (npm install -g adguard-mail-mcp). If you prefer not to install globally, use: npx -p adguard-mail-mcp agm login

This opens a browser window. Sign in to your AdGuard Mail account, and the session token will be captured automatically.

2. Add to your MCP client

Add to your MCP settings (Claude Desktop, Cursor, Antigravity, VS Code, etc.):

{
  "mcpServers": {
    "adguard-mail": {
      "command": "npx",
      "args": ["-y", "adguard-mail-mcp"]
    }
  }
}

Available tools (25)

Auth (4)

setup_auth · re_auth · auth_status · cleanup_data

Account (3)

get_account_overview · get_account_limits · list_domains

Aliases (5)

list_aliases · get_alias · create_alias · update_alias · delete_alias

Recipients (4)

list_recipients · get_recipient · create_recipient · delete_recipient

Temp Mail (9)

list_temp_mailboxes · get_temp_mailbox · create_temp_mailbox · delete_temp_mailbox · list_temp_messages · read_temp_message · wait_for_message · get_latest_otp · extract_verification_links

CLI commands

After global install (npm install -g adguard-mail-mcp):

agm login                  # Login to AdGuard Mail
agm login --profile work   # Login with a named profile
agm status                 # Check auth status
agm discover               # Capture API traffic for debugging
agm cleanup                # Delete all local data

Without global install, prefix with npx -p adguard-mail-mcp:

npx -p adguard-mail-mcp agm login
npx -p adguard-mail-mcp agm status

Multi-profile support

agm login --profile personal
agm login --profile work

{
  "mcpServers": {
    "adguard-personal": {
      "command": "npx",
      "args": ["-y", "adguard-mail-mcp"],
      "env": { "ADGUARD_PROFILE": "personal" }
    },
    "adguard-work": {
      "command": "npx",
      "args": ["-y", "adguard-mail-mcp"],
      "env": { "ADGUARD_PROFILE": "work" }
    }
  }
}

How it works

1. Launches Chrome/Edge/Brave with --remote-debugging-port via CDP (no Puppeteer)
2. Captures Bearer token from network requests during login
3. Calls AdGuard Mail private APIs for aliases, recipients, and temp mail
4. Exposes 25 tools over MCP stdio
5. Auth data stored in ~/.adguard-mail-mcp/ with restricted file permissions

Cross-platform: Windows, macOS, Linux. Requires Node.js >= 18.

Notes

• Set ADGUARD_DATA_DIR env var to change the storage location
• Token/cookie values are redacted in logs and tool outputs
• Retry with exponential backoff and rate limiting (5 req/s)
• Use update_alias with enabled: true/false to enable/disable aliases

License

MIT