JUHE API Marketplace
yunfeizhu avatar
MCP Server

MCP Mail Server

A Model Context Protocol server that enables email operations through POP3 and SMTP protocols in Cursor AI, allowing users to send, receive, list, and manage emails using natural language commands.

19
GitHub Stars
3/10/2026
Last Updated
MCP Server Configuration
1{
2 "name": "mcp-mail-server",
3 "command": "npx",
4 "args": [
5 "-y",
6 "mcp-mail-server"
7 ],
8 "env": {
9 "IMAP_HOST": "your-imap-server.com",
10 "IMAP_PORT": "993",
11 "IMAP_SECURE": "true",
12 "SMTP_HOST": "your-smtp-server.com",
13 "SMTP_PORT": "465",
14 "SMTP_SECURE": "true",
15 "EMAIL_USER": "your-email@domain.com",
16 "EMAIL_PASS": "your-password"
17 }
18}
JSON18 lines
  1. Home
  3. MCP Servers
  5. mcp-mail-server

README Documentation

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

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": ["-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

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
get_message_countGet total message count in current mailbox
get_unseen_messagesGet all unread emails
get_recent_messagesGet recent emails
search_by_senderFind emails from specific sender
search_by_subjectSearch by subject keywords
search_by_recipientFind emails sent to specific recipient
search_by_bodySearch message body content
search_since_dateFind emails since date
search_unread_from_senderFind unread emails from specific sender
search_unreplied_from_senderFind unreplied emails from specific sender
search_with_keywordSearch emails by keyword/flag
search_all_messagesSearch all messages with optional date range and limit
get_messageRetrieve email by UID
get_messagesRetrieve multiple emails
delete_messageDelete email by UID
send_emailSend email via SMTP (with optional attachments)
reply_to_emailReply to specific email
get_attachmentsGet attachment metadata for an email
save_attachmentDownload 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

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

Package Information:

  • Package: mcp-mail-server
  • Node.js: ≥18.0.0
  • Repository: GitHub
  • Issues: Report bugs

Quick Install

Quick Actions

View on GitHubView All Servers

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source

Boost your projects with Wisdom Gate LLM API

Supporting GPT-5, Claude-4, DeepSeek v3, Gemini and more.

Enjoy a free trial and save 20%+ compared to official pricing.

Learn More
JUHE API Marketplace

Accelerate development, innovate faster, and transform your business with our comprehensive API ecosystem.

JUHE API VS

  • vs. RapidAPI
  • vs. API Layer
  • API Platforms 2025
  • API Marketplaces 2025
  • Best Alternatives to RapidAPI

For Developers

  • Console
  • Collections
  • Documentation
  • MCP Servers
  • Free APIs
  • Temp Mail Demo

Product

  • Browse APIs
  • Suggest an API
  • Wisdom Gate LLM
  • Global SMS Messaging
  • Temp Mail API

Company

  • What's New
  • Welcome
  • About Us
  • Contact Support
  • Terms of Service
  • Privacy Policy
Featured on Startup FameFeatured on Twelve ToolsFazier badgeJuheAPI Marketplace - Connect smarter, beyond APIs | Product Huntai tools code.marketDang.aiFeatured on ShowMeBestAI
Copyright © 2026 JUHEDATA HK LIMITED - All rights reserved