Skip to main content
This guide walks you through setting up your first IMAP account and testing the connection. You’ll go from zero to working in just a few steps.

​
Prerequisites

Before you begin, ensure you have:
1

MCP-compatible client

Install Claude Desktop or another MCP client that supports stdio servers.
2

IMAP credentials

Obtain your IMAP server credentials:
  • Host: IMAP server hostname (e.g., imap.gmail.com)
  • User: Your email address
  • Password: App-specific password (not your account password)
3

Node.js (for npm method)

Install Node.js 18 or later if using the npm installation method.
Never use your main email password. Always generate app-specific passwords for IMAP access. See your provider’s documentation for instructions:

​
Configure Claude Desktop

Add the Mail IMAP MCP Server to your Claude Desktop configuration. The configuration file location varies by platform:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "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"
      }
    }
  }
}
Replace [email protected] and your-app-password with your actual credentials. The DEFAULT account is used when no specific account is requested.

​
Environment Variables

The server supports several configuration options via environment variables. Here are the most common ones:
VariableTypeDefaultDescription
MAIL_IMAP_DEFAULT_HOSTstringrequiredIMAP server hostname
MAIL_IMAP_DEFAULT_USERstringrequiredUsername for authentication
MAIL_IMAP_DEFAULT_PASSstringrequiredPassword (use app-specific password)
MAIL_IMAP_DEFAULT_PORTnumber993IMAP server port
MAIL_IMAP_DEFAULT_SECUREbooleantrueUse TLS (currently enforced)
MAIL_IMAP_WRITE_ENABLEDbooleanfalseEnable write operations
MAIL_IMAP_CONNECT_TIMEOUT_MSnumber30000TCP connection timeout
MAIL_IMAP_GREETING_TIMEOUT_MSnumber15000IMAP greeting timeout
MAIL_IMAP_SOCKET_TIMEOUT_MSnumber300000Socket I/O timeout
MAIL_IMAP_CURSOR_TTL_SECONDSnumber600Cursor time-to-live
MAIL_IMAP_CURSOR_MAX_ENTRIESnumber512Maximum cursors to retain
See Environment Variables for complete documentation.

​
Enable Write Operations

By default, write operations (copy, move, delete, flag updates) are disabled for safety. To enable them, add: 
{
  "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",
        "MAIL_IMAP_WRITE_ENABLED": "true"
      }
    }
  }
}
Write operations can modify or delete messages. Only enable this if you trust the MCP client making requests.

​
Test the Connection

After configuring Claude Desktop, restart the application and test the connection:
1

List accounts

Ask Claude: “List my IMAP accounts”Expected response:
{
  "summary": "1 account(s) configured",
  "data": {
    "accounts": [
      {
        "account_id": "default",
        "host": "imap.gmail.com",
        "port": 993,
        "secure": true
      }
    ]
  }
}
2

Verify connectivity

Ask Claude: “Verify my default IMAP account”This tests TCP/TLS connection, authentication, and retrieves server capabilities. Expected response includes "ok": true and a list of IMAP capabilities.
3

List mailboxes

Ask Claude: “List mailboxes in my default account”This returns all visible folders/mailboxes like INBOX, Sent, Drafts, etc.
4

Search messages

Ask Claude: “Search for recent unread messages in INBOX”This tests message search functionality with pagination support.

​
Multiple Accounts

Configure multiple IMAP accounts by adding account-specific environment variables: 
{
  "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-1",
        
        "MAIL_IMAP_WORK_HOST": "outlook.office365.com",
        "MAIL_IMAP_WORK_USER": "[email protected]",
        "MAIL_IMAP_WORK_PASS": "app-password-2",
        
        "MAIL_IMAP_PERSONAL_HOST": "imap.fastmail.com",
        "MAIL_IMAP_PERSONAL_USER": "[email protected]",
        "MAIL_IMAP_PERSONAL_PASS": "app-password-3"
      }
    }
  }
}
The server automatically discovers accounts by scanning for MAIL_IMAP_*_HOST patterns. Account IDs are normalized to lowercase (e.g., WORK becomes work).
When calling MCP tools, specify the account using the normalized account ID: "account_id": "work" or "account_id": "personal".
See Multi-Account Configuration for detailed examples.

​
Troubleshooting

​
Authentication failed

Error: authentication failed: [AUTHENTICATIONFAILED] Authentication failed.
Solutions:
  1. Verify username and password are correct
  2. Use app-specific password (not your main account password)
  3. Check that IMAP is enabled on your account
  4. Ensure 2FA is configured if required by your provider
See Authentication Troubleshooting for more help.

​
Connection timeout

Error: operation timed out: tcp connect timeout
Solutions:
  1. Check your internet connection
  2. Verify the IMAP host and port are correct
  3. Increase timeout: "MAIL_IMAP_CONNECT_TIMEOUT_MS": "60000"
  4. Check if firewall is blocking port 993
See Connection Issues for more help.

​
Write operations disabled

Error: invalid input: write tools are disabled; set MAIL_IMAP_WRITE_ENABLED=true
Solution: Add "MAIL_IMAP_WRITE_ENABLED": "true" to the env section in your configuration.

​
Account not configured

Error: invalid input: account 'myaccount' is not configured
Solution: Verify the account ID exists in environment variables. Account IDs must have MAIL_IMAP_<ID>_HOST, _USER, and _PASS variables defined.

​
Available Tools

The server provides 10 MCP tools for email operations:

​
Read operations (always enabled)

  • imap_list_accounts: List configured accounts
  • imap_verify_account: Test connectivity and capabilities
  • imap_list_mailboxes: List mailboxes/folders
  • imap_search_messages: Search with cursor pagination
  • imap_get_message: Get parsed message details
  • imap_get_message_raw: Get RFC822 source

​
Write operations (require MAIL_IMAP_WRITE_ENABLED=true)

  • imap_update_message_flags: Add/remove flags
  • imap_copy_message: Copy to mailbox
  • imap_move_message: Move to mailbox
  • imap_delete_message: Delete message (requires confirmation)
See API Reference for detailed documentation of each tool.

​
Next Steps

Search messages

Learn cursor-based pagination and search filters

Configure accounts

Deep dive into account configuration options

API reference

Explore all 10 MCP tools and their parameters

Security

Learn about security features and best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us