📦

mail-server

MCP server for IMAP/SMTP email access with environment-based configuration

0 installs

Trust: 42 — Fair

Devtools

Installation

npx mcp-mail-server

Ask AI about mail-server

I know everything about mail-server. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

MCP Mail Server

NPM Version

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
Attachment Management: View attachment metadata and save attachments to local files
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

Changelog

[1.2.1] - 2026-03-18

Fixed

Fixed search criteria (FROM/TO/SUBJECT/BODY/KEYWORD/SINCE) not using nested array format, causing errors on TO and other searches
Fixed search() wrapping criteria in an extra array, breaking compound search conditions
Fixed deleteMessage() failing silently when the mailbox was opened in read-only mode
Fixed getRecentMessages() misusing the IMAP RECENT flag; now fetches latest N messages by UID
Fixed getRecentMessages() / getUnseenMessages() relying on leftover mailbox state from previous operations
Fixed cleanReplySubject() only stripping one Re: prefix layer, causing false negatives in unreplied detection
Fixed email date stored as locale string causing inconsistent new Date() parsing across platforms; changed to ISO 8601
Fixed ensureIMAPConnection() having no timeout while waiting for concurrent initialization
Fixed saveSentMessage() always returning sentFolderSaved: true even when save failed
Fixed handleGetMessages() / handleDeleteMessage() relying on currentBox state to locate messages
Fixed reply_to_email writing literal "undefined" into the body when text is empty

Added

All search tools now support an inboxOnly parameter to restrict search to INBOX only

Improved

ensureSMTPConnection() now has concurrency guard with 30-second timeout, consistent with IMAP
Sent mailbox auto-detected via RFC 6154 \Sent special-use attribute with result caching, compatible with all mail providers
saveMessageToFolder() simplified; skips saving if no sent folder is found
Search now uses slice(-limit) to fetch the newest messages first, preventing empty results after date filtering
HTML-escape applied to quoted content in reply emails to prevent XSS injection

For the full version history, see CHANGELOG.md.

Quick Start

Install: npm install -g mcp-mail-server
Configure environment variables (see Configuration)
Add to your MCP client configuration
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": ["-y", "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": ["-y", "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"
      }
    }
  }
}

Claude Code

Add using the claude mcp add command:

claude mcp add mcp-mail-server \
  -e IMAP_HOST=your-imap-server.com \
  -e IMAP_PORT=993 \
  -e IMAP_SECURE=true \
  -e SMTP_HOST=your-smtp-server.com \
  -e SMTP_PORT=465 \
  -e SMTP_SECURE=true \
  -e EMAIL_USER=your-email@domain.com \
  -e EMAIL_PASS=your-password \
  -- npx -y mcp-mail-server

Or manually add to .claude/settings.json:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "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"
      }
    }
  }
}

OpenAI Codex

Add to codex.json in your project root:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "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

Other MCP clients can be configured similarly. The core configuration is:

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "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"
      }
    }
  }
}

Refer to your specific client's documentation for the appropriate configuration file location.

Available Tools

Tool	Description
`connect_all`	Connect to both IMAP and SMTP servers
`get_connection_status`	Check connection status and server info
`disconnect_all`	Disconnect from all servers
`open_mailbox`	Open specific mailbox/folder
`list_mailboxes`	List available mail folders
`get_message_count`	Get total message count in current mailbox
`get_unseen_messages`	Get all unread emails
`get_recent_messages`	Get recent emails
`search_by_sender`	Find emails from specific sender
`search_by_subject`	Search by subject keywords
`search_by_recipient`	Find emails sent to specific recipient
`search_by_body`	Search message body content
`search_since_date`	Find emails since date
`search_unread_from_sender`	Find unread emails from specific sender
`search_unreplied_from_sender`	Find unreplied emails from specific sender
`search_with_keyword`	Search emails by keyword/flag
`search_all_messages`	Search all messages with optional date range and limit
`get_message`	Retrieve email by UID
`get_messages`	Retrieve multiple emails
`delete_message`	Delete email by UID
`send_email`	Send email via SMTP (with optional attachments)
`reply_to_email`	Reply to specific email
`get_attachments`	Get attachment metadata for an email
`save_attachment`	Download and save attachments to local files

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_by_sender: sender (string, email address), startDate (string, optional), endDate (string, optional)
search_by_subject: subject (string, keywords), startDate (string, optional), endDate (string, optional)
search_by_recipient: recipient (string, email address), startDate (string, optional), endDate (string, optional)
search_by_body: text (string, search text), startDate (string, optional), endDate (string, optional)
search_since_date: date (string, date format)
search_unread_from_sender: sender (string, email address), startDate (string, optional), endDate (string, optional)
search_unreplied_from_sender: sender (string, email address), startDate (string, optional), endDate (string, optional), limit (number, optional)
search_with_keyword: keyword (string, keyword), startDate (string, optional), endDate (string, optional)
search_all_messages: startDate (string, optional), endDate (string, optional), limit (number, optional, default: 50)

Message Operations

get_message_count: No parameters required
get_unseen_messages: No parameters required
get_recent_messages: No parameters required
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), attachments (string[], optional, absolute file paths)
reply_to_email: originalUid (number), text (string), html (string, optional), replyToAll (boolean, optional), includeOriginal (boolean, optional)

Attachment Operations

get_attachments: uid (number) — Returns metadata: filename, contentType, size, index
save_attachment: uid (number), savePath (string, absolute path), attachmentIndex (number, optional, 0-based), returnBase64 (boolean, optional, default: false)

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"
"Search emails sent to team@company.com"
"Get all emails from the Sales folder"
"Show unread emails from boss@company.com"
"Show me all emails from the last 7 days"
"List all messages, limit to 20"

Email Management

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

Attachment Operations

"Show me the attachments of email UID 456"
"Save all attachments from email UID 456 to D:/Downloads"
"Download the first attachment from email UID 789"
"Send an email to team@company.com with attachment D:/report.pdf"

Configuration

Environment Variables

⚠️ All variables are required

Variable	Description	Example
`IMAP_HOST`	IMAP server address	`imap.gmail.com`
`IMAP_PORT`	IMAP port number	`993`
`IMAP_SECURE`	Enable TLS	`true`
`SMTP_HOST`	SMTP server address	`smtp.gmail.com`
`SMTP_PORT`	SMTP port number	`465`
`SMTP_SECURE`	Enable SSL	`true`
`EMAIL_USER`	Email username	`your-email@gmail.com`
`EMAIL_PASS`	Email password/app password	`your-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

Clone the repository:

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

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

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

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

mail-server

Installation

Reviews

Documentation

MCP Mail Server

Features

Changelog

[1.2.1] - 2026-03-18

Quick Start

Installation

Available Tools

Connection Management

Mailbox Operations

Search Operations

Message Operations

Email Sending

Attachment Operations

Usage Examples

Basic Operations

Advanced Searches

Email Management

Attachment Operations

Configuration

Environment Variables

Common Email Providers

Security Notes

Development

Contributing

License

Tags

Security Checklist