Authentication

This page covers authentication-related errors and credential problems.

Authentication Failures

Error: authentication failed: [AUTHENTICATIONFAILED] ...

Error Code: auth_failedFull Message Examples:

Error: authentication failed: [AUTHENTICATIONFAILED] Authentication failed.
Error: authentication failed: [AUTHENTICATIONFAILED] Invalid credentials
Error: authentication failed: [AUTHENTICATIONFAILED] Application-specific password required

Cause:

Incorrect username or password
Using account password instead of app-specific password
Account requires two-factor authentication setup
Account locked or disabled
IMAP access not enabled for account

Solutions:

1. Verify Credentials

Double-check username and password:

Username is usually your full email address
Password is case-sensitive
No extra spaces or hidden characters

2. Use App-Specific Password

Most providers require app passwords when 2FA is enabled:Gmail:

Enable 2-Step Verification: https://myaccount.google.com/security
Generate App Password: https://myaccount.google.com/apppasswords
Use the 16-character app password (remove spaces)

Outlook/Office 365:

Enable 2FA: https://account.microsoft.com/security
Generate App Password in Security settings
Use app password instead of account password

Yahoo:

Enable 2FA in Account Security
Generate App Password: https://login.yahoo.com/account/security
Use the generated password

iCloud:

Enable 2FA: https://appleid.apple.com/account/manage
Generate App-Specific Password
Use app password for IMAP

3. Enable IMAP Access

Some providers disable IMAP by default:Gmail:

Settings → Forwarding and POP/IMAP → Enable IMAP
URL: https://mail.google.com/mail/u/0/#settings/fwdandpop

Outlook:

Settings → Mail → Sync email → POP and IMAP
Ensure IMAP is enabled

4. Check Account Status

Verify account is not locked or suspended
Check for security alerts from your provider
Ensure billing is current (for paid accounts)

5. Test with Official Client

Verify credentials work with the provider’s official app:

If official app also fails, reset your password
If official app works but MCP fails, regenerate app password

Error: authentication failed: [AUTHENTICATIONFAILED] Web login required

Error Code: auth_failedFull Message:

Error: authentication failed: [AUTHENTICATIONFAILED] Web login required: https://...

Cause: Provider requires browser-based authentication (OAuth 2.0 flow) or account verification.Solution:

Gmail/Google Workspace

Open the URL provided in the error message
Sign in with your Google account
Grant access to IMAP
Generate a new app password: https://myaccount.google.com/apppasswords
Update your configuration with the new app password

Office 365

Some organizations disable basic auth for IMAP:

Contact your IT administrator
Request IMAP access or OAuth 2.0 support
May need to use Exchange Web Services instead

Note

This MCP server uses LOGIN authentication. OAuth 2.0 is not currently supported.

Error: authentication failed: Too many login failures

Error Code: auth_failedFull Message:

Error: authentication failed: [AUTHENTICATIONFAILED] Too many login failures

Cause: Account temporarily locked due to multiple failed login attempts.Solution:

1. Wait Before Retrying

Gmail: Wait 15-30 minutes
Outlook: Wait 30-60 minutes
Other providers: Wait 1 hour

2. Verify Credentials

While waiting, verify your credentials are correct:

Check for typos in password
Ensure you’re using app password (if required)
Test credentials in official email client

3. Reset Password if Needed

If you’re unsure about credentials:

Reset account password
Regenerate app-specific password
Update MCP configuration

4. Check for Multiple Clients

Ensure no other clients are failing authentication
Stop other IMAP clients temporarily
Clear saved credentials in other apps

Error: not found: account 'default' is not configured

Error Code: not_foundFull Message:

Error: not found: account 'default' is not configured

Cause: No IMAP account is configured in the environment.Solution:

Configure Default Account

Add these environment variables to your MCP 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": "your-app-password"
      }
    }
  }
}

Required Variables

MAIL_IMAP_DEFAULT_HOST - IMAP server hostname
MAIL_IMAP_DEFAULT_USER - Full email address or username
MAIL_IMAP_DEFAULT_PASS - App-specific password

Optional Variables

MAIL_IMAP_DEFAULT_PORT=993      # Default: 993
MAIL_IMAP_DEFAULT_SECURE=true   # Default: true (required)

Provider-Specific Setup

Gmail

Setting up Gmail IMAP access

Requirements:

2-Step Verification must be enabled
App password required (cannot use account password)
IMAP must be enabled in settings

Step-by-Step:

Enable 2-Step Verification:
- Go to https://myaccount.google.com/security
- Click “2-Step Verification” → “Get Started”
- Follow the setup wizard
Enable IMAP:
- Go to https://mail.google.com/mail/u/0/#settings/fwdandpop
- Under “IMAP access”, select “Enable IMAP”
- Click “Save Changes”
Generate App Password:
- Go to https://myaccount.google.com/apppasswords
- Select “Mail” and your device/app name
- Click “Generate”
- Copy the 16-character password (ignore spaces)

Configure MCP Server:

{
  "env": {
    "MAIL_IMAP_DEFAULT_HOST": "imap.gmail.com",
    "MAIL_IMAP_DEFAULT_PORT": "993",
    "MAIL_IMAP_DEFAULT_USER": "[email protected]",
    "MAIL_IMAP_DEFAULT_PASS": "abcd efgh ijkl mnop"
  }
}

Common Issues:

“Less secure app access”: Not needed (deprecated by Google)
App password option missing: Enable 2-Step Verification first
Authentication still fails: Regenerate app password

Microsoft Outlook / Office 365

Setting up Outlook/Office 365 IMAP access

Requirements:

IMAP must be enabled by organization
Basic authentication must be allowed
App password if 2FA is enabled

Step-by-Step:

Check IMAP Status:
- Go to https://outlook.office.com/mail/options/mail/accounts
- Look for “POP and IMAP” settings
- Ensure IMAP is enabled
Enable 2FA (if not enabled):
- Go to https://account.microsoft.com/security
- Set up two-step verification
Generate App Password:
- In Security settings, find “App passwords”
- Create new password for “Email”
- Copy the generated password

Configure MCP Server:

{
  "env": {
    "MAIL_IMAP_DEFAULT_HOST": "outlook.office365.com",
    "MAIL_IMAP_DEFAULT_PORT": "993",
    "MAIL_IMAP_DEFAULT_USER": "[email protected]",
    "MAIL_IMAP_DEFAULT_PASS": "app-password-here"
  }
}

Organization Accounts: If you have a work/school account:

Contact IT administrator if IMAP is disabled
Modern authentication (OAuth) may be required
Basic auth might be disabled by policy

Common Issues:

“Basic authentication disabled”: Contact IT to enable
“IMAP not available”: Organization policy - use Exchange instead
Host varies: Some use imap-mail.outlook.com

Yahoo Mail

Setting up Yahoo Mail IMAP access

Requirements:

Account must have IMAP enabled
App password required (account password won’t work)

Step-by-Step:

Generate App Password:
- Go to https://login.yahoo.com/account/security
- Click “Generate app password”
- Select “Other App” and enter a name
- Click “Generate”
- Copy the password immediately (shown only once)

Configure MCP Server:

{
  "env": {
    "MAIL_IMAP_DEFAULT_HOST": "imap.mail.yahoo.com",
    "MAIL_IMAP_DEFAULT_PORT": "993",
    "MAIL_IMAP_DEFAULT_USER": "[email protected]",
    "MAIL_IMAP_DEFAULT_PASS": "app-password-here"
  }
}

Note: Yahoo requires app passwords even without 2FA.

iCloud Mail

Setting up iCloud Mail IMAP access

Requirements:

Two-factor authentication must be enabled
App-specific password required

Step-by-Step:

Enable 2FA:
- Go to https://appleid.apple.com/account/manage
- Sign in with your Apple ID
- Enable Two-Factor Authentication if not already on
Generate App Password:
- In account settings, go to “Security” section
- Under “App-Specific Passwords”, click “Generate Password”
- Enter a label (e.g., “IMAP MCP”)
- Copy the generated password

Configure MCP Server:

{
  "env": {
    "MAIL_IMAP_DEFAULT_HOST": "imap.mail.me.com",
    "MAIL_IMAP_DEFAULT_PORT": "993",
    "MAIL_IMAP_DEFAULT_USER": "[email protected]",
    "MAIL_IMAP_DEFAULT_PASS": "app-specific-password"
  }
}

Alternative Hosts:

imap.mail.me.com (primary)
imap.mail.icloud.com (alternative)

Fastmail

Setting up Fastmail IMAP access

Requirements:

App password recommended
Standard IMAP enabled by default

Step-by-Step:

Generate App Password:
- Go to Settings → Security → App Passwords
- Click “New App Password”
- Give it a name and select appropriate access
- Copy the generated password

Configure MCP Server:

{
  "env": {
    "MAIL_IMAP_DEFAULT_HOST": "imap.fastmail.com",
    "MAIL_IMAP_DEFAULT_PORT": "993",
    "MAIL_IMAP_DEFAULT_USER": "[email protected]",
    "MAIL_IMAP_DEFAULT_PASS": "app-password-here"
  }
}

Note: Fastmail allows account password, but app passwords are more secure.

Security Best Practices

Password Management

Always Use App-Specific Passwords
- Never use your main account password
- App passwords can be revoked individually
- Limits damage if credentials are compromised
Store Passwords Securely
- Use environment variables (never hardcode)
- Use secrets management tools
- Keep configuration files out of version control
Rotate Passwords Regularly
- Regenerate app passwords periodically
- Revoke unused app passwords
- Monitor account activity

Environment Variable Security

# ✓ Good - Using environment file
echo 'MAIL_IMAP_DEFAULT_PASS=secret' >> ~/.env.mail
chmod 600 ~/.env.mail
source ~/.env.mail

# ✗ Bad - Password in command history
export MAIL_IMAP_DEFAULT_PASS=secret

# ✗ Bad - Password in config file in git
cat > config.json << EOF
{"pass": "secret"}
EOF

Monitoring

Enable Login Alerts
- Most providers can email on new logins
- Review security activity regularly
Review Connected Apps
- Periodically review app passwords
- Revoke access for unused apps
Check for Suspicious Activity
- Monitor for failed login attempts
- Check account activity logs

Troubleshooting Checklist

When authentication fails, verify in order:

Credentials are correct (no typos)
Using app-specific password (not account password)
IMAP is enabled in account settings
Account is not locked or suspended
2FA is properly configured
No connection/network issues
Server hostname and port are correct
Environment variables are loaded correctly
No extra spaces in username/password

Connection Issues - Network and timeout problems
Common Errors - Other frequent errors
Configuration Guide - Complete configuration reference
Security Considerations - Security best practices

Get Started

Configuration

Core Concepts

Guides

Security

Troubleshooting

Authentication Failures

1. Verify Credentials

2. Use App-Specific Password

3. Enable IMAP Access

4. Check Account Status

5. Test with Official Client

Configure Default Account

Required Variables

Optional Variables

Provider-Specific Setup

Gmail

Microsoft Outlook / Office 365

Yahoo Mail

iCloud Mail

Fastmail

Security Best Practices

Password Management

Environment Variable Security

Monitoring

Troubleshooting Checklist

Build docs developers (and LLMs) love

Get Started

Configuration

Core Concepts

Guides

Security

Troubleshooting

​Authentication Failures

​1. Verify Credentials

​2. Use App-Specific Password

​3. Enable IMAP Access

​4. Check Account Status

​5. Test with Official Client

​Gmail/Google Workspace

​Office 365

​Note

​1. Wait Before Retrying

​2. Verify Credentials

​3. Reset Password if Needed

​4. Check for Multiple Clients

​Configure Default Account

​Required Variables

​Optional Variables

​Provider-Specific Setup

​Gmail

​Microsoft Outlook / Office 365

​Yahoo Mail

​iCloud Mail

​Fastmail

​Security Best Practices

​Password Management

​Environment Variable Security

​Monitoring

​Troubleshooting Checklist

​Related Documentation

Build docs developers (and LLMs) love

Authentication Failures

1. Verify Credentials

2. Use App-Specific Password

3. Enable IMAP Access

4. Check Account Status

5. Test with Official Client

Gmail/Google Workspace

Office 365

Note

1. Wait Before Retrying

2. Verify Credentials

3. Reset Password if Needed

4. Check for Multiple Clients

Configure Default Account

Required Variables

Optional Variables

Provider-Specific Setup

Gmail

Microsoft Outlook / Office 365

Yahoo Mail

iCloud Mail

Fastmail

Security Best Practices

Password Management

Environment Variable Security

Monitoring

Troubleshooting Checklist

Related Documentation