mcp-mail-server

yunfeizhu/mcp-mail-server

3.4

If you are the rightful owner of mcp-mail-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 MCP Mail Server is a Model Context Protocol server designed to facilitate email operations using IMAP and SMTP protocols within Cursor AI, offering a secure and efficient email management solution.

Tools
5
Resources
0
Prompts
0

MCP Mail Server

NPM Version License: MIT

Language: English |

A Model Context Protocol server for IMAP/SMTP email operations with Claude, Cursor, and other AI assistants.

Features

  • IMAP Operations: Search, read, and manage emails across mailboxes
  • SMTP Support: Send emails with HTML/text content and attachments
  • Secure Configuration: Environment-based setup with TLS/SSL support
  • AI-Friendly: Natural language commands for email operations
  • Auto Connection Management: Automatic IMAP/SMTP connection handling
  • Multi-Mailbox Support: Access INBOX, Sent, and custom folders

Quick Start

  1. Install: npm install -g mcp-mail-server
  2. Configure environment variables (see Configuration)
  3. Add to your MCP client configuration
  4. Use natural language: "Show me unread emails from today"

Installation

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}
Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}
Other MCP Clients

For global installation:

npm install -g mcp-mail-server

Then configure with:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "mcp-mail-server"
    }
  }
}

Available Tools

ToolDescription
connect_allConnect to both IMAP and SMTP servers
get_connection_statusCheck connection status and server info
disconnect_allDisconnect from all servers
open_mailboxOpen specific mailbox/folder
list_mailboxesList available mail folders
search_messagesSearch emails with IMAP criteria
search_by_senderFind emails from specific sender
search_by_subjectSearch by subject keywords
search_by_bodySearch message content
search_since_dateFind emails since date
search_unreplied_from_senderFind unreplied emails from specific sender
search_larger_thanFind emails by size
get_messageRetrieve email by UID
get_messagesRetrieve multiple emails
delete_messageDelete email by UID
get_unseen_messagesGet all unread emails
get_recent_messagesGet recent emails
send_emailSend email via SMTP
reply_to_emailReply to specific email
Detailed Tool Parameters

Connection Management

  • connect_all: No parameters required
  • get_connection_status: No parameters required
  • disconnect_all: No parameters required

Mailbox Operations

  • open_mailbox: mailboxName (string, default: "INBOX"), readOnly (boolean)
  • list_mailboxes: No parameters required

Search Operations

  • search_messages: criteria (array, IMAP search criteria)
  • search_by_sender: sender (string, email address)
  • search_by_subject: subject (string, keywords)
  • search_by_body: text (string, search text)
  • search_since_date: date (string, date format)
  • search_unreplied_from_sender: sender (string, email address), startDate (string, optional), endDate (string, optional)
  • search_larger_than: size (number, bytes)

Message Operations

  • get_message: uid (number), markSeen (boolean, optional)
  • get_messages: uids (array), markSeen (boolean, optional)
  • delete_message: uid (number)

Email Sending

  • send_email: to (string), subject (string), text (string, optional), html (string, optional), cc (string, optional), bcc (string, optional)
  • reply_to_email: originalUid (number), text (string), html (string, optional), replyToAll (boolean, optional), includeOriginal (boolean, optional)

Usage Examples

Use natural language commands with your AI assistant:

Basic Operations

  • "Connect to my email servers"
  • "Show me all unread emails"
  • "Search for emails from boss@company.com"
  • "Send an email to team@company.com about the meeting"
  • "Reply to email with UID 123"

Advanced Searches

  • "Find emails with 'urgent' in the subject from last week"
  • "Show me unreplied emails from boss@company.com"
  • "Show me large emails over 5MB"
  • "Get all emails from the Sales folder"

Email Management

  • "Delete the email with UID 123"
  • "Mark recent emails as read"
  • "List all my email folders"

Configuration

Environment Variables

⚠️ All variables are required

VariableDescriptionExample
IMAP_HOSTIMAP server addressimap.gmail.com
IMAP_PORTIMAP port number993
IMAP_SECUREEnable TLStrue
SMTP_HOSTSMTP server addresssmtp.gmail.com
SMTP_PORTSMTP port number465
SMTP_SECUREEnable SSLtrue
EMAIL_USEREmail usernameyour-email@gmail.com
EMAIL_PASSEmail password/app passwordyour-app-password

Common Email Providers

Gmail Configuration 
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

Note: Use App Passwords instead of your regular password.

Outlook/Hotmail Configuration 
IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=true
EMAIL_USER=your-email@outlook.com
EMAIL_PASS=your-password

Security Notes

  • Use App Passwords: Enable 2FA and use app-specific passwords when available
  • TLS/SSL Required: Always use secure connections (IMAP_SECURE=true, SMTP_SECURE=true)
  • Environment Variables: Never hardcode credentials in configuration files

Development

Local Development Setup

  1. Clone the repository:

    git clone https://github.com/yunfeizhu/mcp-mail-server.git
cd mcp-mail-server

  2. Install dependencies:

    npm install

  3. Build the project:

    npm run build

  4. Set environment variables:

    export IMAP_HOST=your-imap-server.com
export IMAP_PORT=993
export IMAP_SECURE=true
export SMTP_HOST=your-smtp-server.com
export SMTP_PORT=465
export SMTP_SECURE=true
export EMAIL_USER=your-email@domain.com
export EMAIL_PASS=your-password

  5. Run the server:

    npm start

Contributing

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

License

MIT License - see file for details.

Package Information: