Skip to main content

​
Overview

The Mail IMAP MCP Server discovers accounts by scanning environment variables following the pattern MAIL_IMAP_<ACCOUNT>_HOST. Each account requires host, user, and password credentials.

​
Single Account Setup

For a single account, use the DEFAULT account identifier: 
MAIL_IMAP_DEFAULT_HOST=imap.gmail.com
MAIL_IMAP_DEFAULT_USER=[email protected]
MAIL_IMAP_DEFAULT_PASS=app-password
The DEFAULT account is normalized to default as the account ID in tool calls.

​
Multiple Accounts

Configure multiple IMAP accounts with unique identifiers: 
# Personal Gmail account
MAIL_IMAP_DEFAULT_HOST=imap.gmail.com
MAIL_IMAP_DEFAULT_USER=[email protected]
MAIL_IMAP_DEFAULT_PASS=app-password-1

# Work Outlook account
MAIL_IMAP_WORK_HOST=outlook.office365.com
MAIL_IMAP_WORK_USER=[email protected]
MAIL_IMAP_WORK_PASS=app-password-2

# Personal Fastmail account
MAIL_IMAP_PERSONAL_HOST=imap.fastmail.com
MAIL_IMAP_PERSONAL_USER=[email protected]
MAIL_IMAP_PERSONAL_PASS=app-password-3

​
Required Variables

These environment variables are required for each account:
​
MAIL_IMAP_<ACCOUNT>_HOST
string
required
IMAP server hostname (e.g., imap.gmail.com, outlook.office365.com)
​
MAIL_IMAP_<ACCOUNT>_USER
string
required
Username for authentication (typically the email address)
​
MAIL_IMAP_<ACCOUNT>_PASS
string
required
Password for authentication
Use app-specific passwords instead of account passwords when available. Passwords are stored using SecretString and never logged or returned in responses.

​
Optional Variables

These environment variables are optional with sensible defaults:
​
MAIL_IMAP_<ACCOUNT>_PORT
number
default:"993"
IMAP server port. Standard IMAPS port is 993 for implicit TLS.
​
MAIL_IMAP_<ACCOUNT>_SECURE
boolean
default:"true"
Whether to use TLS encryption. Currently enforced to true.
Only implicit TLS (IMAPS) on port 993 is supported. STARTTLS is not supported.

​
Account ID Rules

  • Pattern: ^[A-Z0-9_]+$ in environment variables (uppercase)
  • Normalized: Converted to lowercase for use in tool calls (except DEFAULT becomes default)
  • Length: 1-64 characters
  • Must be unique across all configured accounts

​
Examples

Environment Variable SegmentNormalized Account ID
DEFAULTdefault
WORKwork
PERSONALpersonal
BACKUPbackup
ARCHIVE_2024archive_2024

​
Account Discovery

The server automatically discovers accounts by scanning for MAIL_IMAP_*_HOST variables at startup:
  1. Scans all environment variables
  2. Finds patterns matching MAIL_IMAP_<SEGMENT>_HOST
  3. Extracts the <SEGMENT> as the account identifier
  4. Loads corresponding USER, PASS, PORT, and SECURE variables
If no accounts are discovered, the server falls back to requiring a DEFAULT account.

​
Common Providers

​
Gmail

MAIL_IMAP_DEFAULT_HOST=imap.gmail.com
MAIL_IMAP_DEFAULT_PORT=993
MAIL_IMAP_DEFAULT_USER=[email protected]
MAIL_IMAP_DEFAULT_PASS=your-app-password
Gmail requires app-specific passwords when 2FA is enabled.

​
Outlook / Office 365

MAIL_IMAP_WORK_HOST=outlook.office365.com
MAIL_IMAP_WORK_PORT=993
MAIL_IMAP_WORK_USER=[email protected]
MAIL_IMAP_WORK_PASS=your-password

​
Fastmail

MAIL_IMAP_PERSONAL_HOST=imap.fastmail.com
MAIL_IMAP_PERSONAL_PORT=993
MAIL_IMAP_PERSONAL_USER=[email protected]
MAIL_IMAP_PERSONAL_PASS=your-app-password

​
iCloud

MAIL_IMAP_ICLOUD_HOST=imap.mail.me.com
MAIL_IMAP_ICLOUD_PORT=993
MAIL_IMAP_ICLOUD_USER=[email protected]
MAIL_IMAP_ICLOUD_PASS=your-app-password
iCloud requires app-specific passwords when 2FA is enabled.

​
Security Best Practices

Never commit .env files to version control. Add .env to your .gitignore file.
  1. Use app-specific passwords instead of account passwords when available
  2. Enable 2FA on your email accounts
  3. Secure .env files with restrictive permissions: chmod 600 .env
  4. Use credential managers for production deployments
  5. Rotate credentials periodically

​
Troubleshooting

​
Account Not Found

Error: invalid input: account "unknown" not configured
Resolution: Verify the account ID exists in environment variables and matches case-sensitivity in tool calls.

​
Missing Required Variables

Error: missing required environment variable: MAIL_IMAP_DEFAULT_HOST
Resolution: Set all required variables (HOST, USER, PASS) for the account.

​
Authentication Failed

Error: authentication failed: [AUTHENTICATIONFAILED] Authentication failed.
Resolution:
  1. Verify USER and PASS are correct
  2. Use app-specific password for Gmail/Outlook/iCloud
  3. Check that the account allows IMAP access
  4. Ensure account is not locked or requiring 2FA challenge

Build docs developers (and LLMs) love

Get started for freeTalk to us