imap-mcp-server

nikolausm/imap-mcp-server

3.2

If you are the rightful owner of imap-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The IMAP MCP Server is a robust Model Context Protocol server designed to integrate IMAP email functionalities with secure account management and efficient connection handling.

Tools
5
Resources
0
Prompts
0

IMAP MCP Server

A powerful Model Context Protocol (MCP) server that provides seamless IMAP email integration with secure account management and connection pooling.

Features

  • šŸ” Secure Account Management: Encrypted credential storage with AES-256 encryption
  • šŸš€ Connection Pooling: Efficient IMAP connection management
  • šŸ“§ Comprehensive Email Operations: Search, read, mark, delete emails
  • āœ‰ļø Email Sending: Send, reply, and forward emails via SMTP
  • šŸ“ Folder Management: List folders, check status, get unread counts
  • šŸ”„ Multiple Account Support: Manage multiple IMAP accounts simultaneously
  • šŸ›”ļø Type-Safe: Built with TypeScript for reliability
  • šŸŒ Web-Based Setup Wizard: Easy account configuration with provider presets
  • šŸ“± 15+ Email Providers: Pre-configured settings for Gmail, Outlook, Yahoo, and more
  • šŸ”— Auto SMTP Configuration: Automatic SMTP settings based on IMAP provider

Installation

Quick Install (Recommended)

macOS/Linux:
curl -fsSL https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.sh | bash
Windows (PowerShell as Administrator):
iwr -useb https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.ps1 | iex

Manual Installation

  1. Clone the repository:
git clone https://github.com/nikolausm/imap-mcp-server.git
cd imap-mcp-server
  1. Install dependencies:
npm install
  1. Build the project:
npm run build

Account Setup

Web-Based Setup Wizard (Recommended)

After installation, run the setup wizard:

npm run setup

Or if installed globally:

imap-setup

This will:

  1. Start a local web server
  2. Open your browser to the setup wizard
  3. Guide you through adding email accounts with pre-configured settings

Supported Email Providers

The setup wizard includes pre-configured settings for:

  • Gmail / Google Workspace
  • Microsoft Outlook / Hotmail / Live
  • Yahoo Mail
  • Apple iCloud Mail
  • GMX
  • WEB.DE
  • IONOS (1&1)
  • ProtonMail (with Bridge)
  • Fastmail
  • Zoho Mail
  • AOL Mail
  • mailbox.org
  • Posteo
  • Custom IMAP servers

Configuration

Claude Desktop Configuration

Add the IMAP MCP server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "imap": {
      "command": "node",
      "args": ["/path/to/ImapClient/dist/index.js"],
      "env": {}
    }
  }
}

Usage

Once configured, the IMAP MCP server provides the following tools in Claude:

Account Management

  • imap_add_account: Add a new IMAP account

    Parameters:
- name: Friendly name for the account
- host: IMAP server hostname
- port: Server port (default: 993)
- user: Username
- password: Password
- tls: Use TLS/SSL (default: true)

  • imap_list_accounts: List all configured accounts

  • imap_remove_account: Remove an account

    Parameters:
- accountId: ID of the account to remove

  • imap_connect: Connect to an account

    Parameters:
- accountId OR accountName: Account identifier

  • imap_disconnect: Disconnect from an account

    Parameters:
- accountId: Account to disconnect

Email Operations

  • imap_search_emails: Search for emails

    Parameters:
- accountId: Account ID
- folder: Folder name (default: INBOX)
- from, to, subject, body: Search criteria
- since, before: Date filters
- seen, flagged: Status filters
- limit: Max results (default: 50)

  • imap_get_email: Get full email content

    Parameters:
- accountId: Account ID
- folder: Folder name
- uid: Email UID

  • imap_get_latest_emails: Get recent emails

    Parameters:
- accountId: Account ID
- folder: Folder name (default: INBOX)
- count: Number of emails (default: 10)

  • imap_mark_as_read/unread: Change email read status

    Parameters:
- accountId: Account ID
- folder: Folder name
- uid: Email UID

  • imap_delete_email: Delete an email

    Parameters:
- accountId: Account ID
- folder: Folder name
- uid: Email UID

  • imap_send_email: Send a new email

    Parameters:
- accountId: Account ID to send from
- to: Recipient email address(es)
- subject: Email subject
- text: Plain text content (optional)
- html: HTML content (optional)
- cc: CC recipients (optional)
- bcc: BCC recipients (optional)
- replyTo: Reply-to address (optional)
- attachments: Array of attachments (optional)
  - filename: Attachment filename
  - content: Base64 encoded content
  - path: File path to attach
  - contentType: MIME type

  • imap_reply_to_email: Reply to an existing email

    Parameters:
- accountId: Account ID
- folder: Folder containing the original email
- uid: UID of the email to reply to
- text: Plain text reply content (optional)
- html: HTML reply content (optional)
- replyAll: Reply to all recipients (default: false)
- attachments: Array of attachments (optional)

  • imap_forward_email: Forward an existing email

    Parameters:
- accountId: Account ID
- folder: Folder containing the original email
- uid: UID of the email to forward
- to: Forward to email address(es)
- text: Additional text to include (optional)
- includeAttachments: Include original attachments (default: true)

Folder Operations

  • imap_list_folders: List all folders

    Parameters:
- accountId: Account ID

  • imap_folder_status: Get folder information

    Parameters:
- accountId: Account ID
- folder: Folder name

  • imap_get_unread_count: Count unread emails

    Parameters:
- accountId: Account ID
- folders: Specific folders (optional)

Security

  • Credentials are encrypted using AES-256-CBC encryption
  • Encryption keys are stored separately in ~/.imap-mcp/.key
  • Account configurations are stored in ~/.imap-mcp/accounts.json
  • Never commit or share your encryption key or account configurations

Development

Running in Development Mode

npm run dev

Building

npm run build

Project Structure

src/
ā”œā”€ā”€ index.ts           # MCP server entry point
ā”œā”€ā”€ services/
ā”‚   ā”œā”€ā”€ imap-service.ts    # IMAP connection management
ā”‚   ā”œā”€ā”€ smtp-service.ts    # SMTP service for sending emails
ā”‚   ā””ā”€ā”€ account-manager.ts # Account configuration
ā”œā”€ā”€ tools/
ā”‚   ā”œā”€ā”€ index.ts          # Tool registration
ā”‚   ā”œā”€ā”€ account-tools.ts  # Account management tools
ā”‚   ā”œā”€ā”€ email-tools.ts    # Email operation tools (including send/reply/forward)
ā”‚   ā””ā”€ā”€ folder-tools.ts   # Folder operation tools
ā””ā”€ā”€ types/
    ā””ā”€ā”€ index.ts          # TypeScript type definitions

Example Usage in Claude

  1. Add an account: "Add my Gmail account with username john@gmail.com"

  2. Check new emails: "Show me the latest 5 emails from my Gmail account"

  3. Search emails: "Search for emails from boss@company.com in the last week"

  4. Send an email: "Send an email to client@example.com with subject 'Project Update'"

  5. Reply to emails: "Reply to the latest email from my boss"

  6. Forward emails: "Forward the email with subject 'Meeting Notes' to team@company.com"

  7. Manage folders: "List all folders in my email account and show unread counts"

Troubleshooting

Connection Issues

  • Ensure your IMAP server settings are correct
  • Check if your email provider requires app-specific passwords
  • Verify that IMAP is enabled in your email account settings
  • For sending emails, ensure your account has SMTP access enabled

SMTP Configuration

The server automatically configures SMTP settings based on your IMAP provider. If you need custom SMTP settings, you can specify them when adding an account:

{
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "secure": false
  }
}

Common IMAP Settings

  • Gmail:

    • Host: imap.gmail.com
    • Port: 993
    • Requires app-specific password

  • Outlook/Hotmail:

    • Host: outlook.office365.com
    • Port: 993

  • Yahoo:

    • Host: imap.mail.yahoo.com
    • Port: 993
    • Requires app-specific password

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.