Skip to main content

​
Overview

The Mail IMAP MCP Server supports multiple IMAP accounts simultaneously. You can configure accounts for Gmail, Outlook, Fastmail, or any IMAP-compatible email service and switch between them seamlessly.

​
Configuration Format

Accounts are configured using environment variables with the pattern MAIL_IMAP_{ACCOUNT_ID}_{SETTING}.

​
Required Settings

Each account requires three essential settings:
  • MAIL_IMAP_{ACCOUNT_ID}_HOST - IMAP server hostname
  • MAIL_IMAP_{ACCOUNT_ID}_USER - Email username
  • MAIL_IMAP_{ACCOUNT_ID}_PASS - App-specific password

​
Optional Settings

  • MAIL_IMAP_{ACCOUNT_ID}_PORT - IMAP port (defaults to 993)
  • MAIL_IMAP_{ACCOUNT_ID}_SECURE - Use TLS (defaults to true)
The server only supports secure TLS connections. Setting SECURE=false will cause connection failures.

​
Setting Up Multiple Accounts

1

Define your default account

The default account is used when no account_id is specified in tool calls.
MAIL_IMAP_DEFAULT_HOST=imap.gmail.com
MAIL_IMAP_DEFAULT_USER=[email protected]
MAIL_IMAP_DEFAULT_PASS=app-password-here
Use app-specific passwords, not your main account password. See your email provider’s documentation for generating app passwords.
2

Add your work account

Create a second account with the identifier WORK:
MAIL_IMAP_WORK_HOST=outlook.office365.com
MAIL_IMAP_WORK_USER=[email protected]
MAIL_IMAP_WORK_PASS=work-app-password
3

Add your personal account

Add a third account with the identifier PERSONAL:
MAIL_IMAP_PERSONAL_HOST=imap.fastmail.com
MAIL_IMAP_PERSONAL_USER=[email protected]
MAIL_IMAP_PERSONAL_PASS=personal-app-password
4

Configure in MCP settings

Add all environment variables to your MCP client configuration:
{
  "mcpServers": {
    "mail-imap": {
      "command": "npx",
      "args": ["-y", "@bradsjm/mail-imap-mcp-rs@latest"],
      "env": {
        "MAIL_IMAP_DEFAULT_HOST": "imap.gmail.com",
        "MAIL_IMAP_DEFAULT_USER": "[email protected]",
        "MAIL_IMAP_DEFAULT_PASS": "app-password-here",
        "MAIL_IMAP_WORK_HOST": "outlook.office365.com",
        "MAIL_IMAP_WORK_USER": "[email protected]",
        "MAIL_IMAP_WORK_PASS": "work-app-password",
        "MAIL_IMAP_PERSONAL_HOST": "imap.fastmail.com",
        "MAIL_IMAP_PERSONAL_USER": "[email protected]",
        "MAIL_IMAP_PERSONAL_PASS": "personal-app-password"
      }
    }
  }
}

​
Using Multiple Accounts

​
List All Configured Accounts

Use the imap_list_accounts tool to see all available accounts without exposing credentials: 
{
  "summary": "3 account(s) configured",
  "data": {
    "accounts": [
      {
        "account_id": "default",
        "host": "imap.gmail.com",
        "port": 993,
        "secure": true
      },
      {
        "account_id": "work",
        "host": "outlook.office365.com",
        "port": 993,
        "secure": true
      },
      {
        "account_id": "personal",
        "host": "imap.fastmail.com",
        "port": 993,
        "secure": true
      }
    ]
  }
}

​
Specify Account in Tool Calls

All tools accept an optional account_id parameter. When omitted, the default account is used. 
{
  "account_id": "work",
  "mailbox": "INBOX",
  "from": "[email protected]",
  "last_days": 7
}

{
  "account_id": "personal"
}
The account_id can be omitted to use the default account:
{
  "message_id": "imap:default:INBOX:1234:567"
}

​
Cross-Account Operations

​
Copy Messages Between Accounts

You can copy messages from one account to another using the imap_copy_message tool: 
{
  "account_id": "work",
  "message_id": "imap:work:INBOX:1234:567",
  "destination_mailbox": "Archive",
  "destination_account_id": "personal"
}
When copying across accounts, the server:
  1. Fetches the raw RFC822 message from the source account
  2. Connects to the destination account
  3. Uses IMAP APPEND to create the message in the destination mailbox
Write operations require MAIL_IMAP_WRITE_ENABLED=true to be set.

​
Common Provider Settings

Host: imap.gmail.com
Port: 993
App Password: Generate here
MAIL_IMAP_GMAIL_HOST=imap.gmail.com
MAIL_IMAP_GMAIL_USER=[email protected]
MAIL_IMAP_GMAIL_PASS=your-app-password
Host: outlook.office365.com
Port: 993
Setup: Enable IMAP
MAIL_IMAP_OUTLOOK_HOST=outlook.office365.com
MAIL_IMAP_OUTLOOK_USER=[email protected]
MAIL_IMAP_OUTLOOK_PASS=your-password
Host: imap.fastmail.com
Port: 993
App Password: Generate here
MAIL_IMAP_FASTMAIL_HOST=imap.fastmail.com
MAIL_IMAP_FASTMAIL_USER=[email protected]
MAIL_IMAP_FASTMAIL_PASS=your-app-password
Host: imap.mail.me.com
Port: 993
App Password: Generate here
MAIL_IMAP_ICLOUD_HOST=imap.mail.me.com
MAIL_IMAP_ICLOUD_USER=[email protected]
MAIL_IMAP_ICLOUD_PASS=your-app-password

​
Security Considerations

​
Password Storage

Passwords configured via environment variables:
  • Are never logged by the server
  • Are never returned in tool responses
  • Should use app-specific passwords, not your main account password

​
Account Isolation

Each account maintains:
  • Independent IMAP sessions
  • Separate authentication
  • Isolated connection pools
Accounts cannot interfere with each other’s operations.

​
Troubleshooting

Error: not found: account 'xyz' not configuredSolution: Ensure environment variables use the exact account ID:
  • Check spelling and capitalization
  • Verify all three required variables are set (HOST, USER, PASS)
Error: authentication failed: [AUTHENTICATIONFAILED]Solution:
  • Use app-specific password, not your account password
  • Verify IMAP access is enabled for the account
  • Check username format (some providers require full email)
Error: operation timed out: tcp connect timeoutSolution:
  • Verify the IMAP host and port are correct
  • Check network/firewall allows connections to port 993
  • Increase timeout: MAIL_IMAP_CONNECT_TIMEOUT_MS=60000

​
Next Steps

Search Messages

Learn how to search and filter messages across accounts

Error Handling

Understand error responses and recovery strategies

Build docs developers (and LLMs) love

Get started for freeTalk to us