MCP Mail Server

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

Add to your claude_desktop_config.json:

Add to your Cursor MCP settings:

For global installation:

Then configure with:

Available Tools

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

• "Send an email to

• "Reply to email with UID 123"

Advanced Searches

• "Find emails with 'urgent' in the subject from last week"

• "Show me unreplied emails from

• "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

Common Email Providers

Note: Use App Passwords instead of your regular 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

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 LICENSE file for details.

Package Information:

• Package: mcp-mail-server

• Node.js: ≥18.0.0

• Repository: GitHub

• Issues: Report bugs