mcp-mail

This MCP server exposes a Mail MCP tool that enables AI models to perform common email operations via a standardized Model Context Protocol interface. It supports sending emails (including HTML content and attachments), reading inboxes and folders, performing advanced searches, managing messages (read/unread, delete, move), handling attachments (listing, downloading, previewing), and managing contacts. With a simple natural-language prompt, the AI can instruct the server to list folders, fetch recent messages, search by keywords or date ranges, or send emails to specified recipients. The underlying implementation uses a Python bridge that communicates with your SMTP/IMAP servers, exposing consistent MCP actions for the AI to consume. When integrated into your Cursor/MCP workflow, you can request tasks like listing mail folders, showing the latest mails, sending test messages, searching for invoices, viewing message details, or downloading attachments, all through natural language commands mapped to the MCP endpoints.

Prerequisites:

• Python 3.11 or newer installed and available on PATH
• Git installed
• Optional: Node.js and npm if you plan to clone/build additional tooling (not required for the Python bridge)

Installation steps:

1. Clone the repository:

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

2. Install Python dependencies (if any are defined; otherwise ensure Python is accessible):

# If a requirements.txt exists, install it
pip install -r requirements.txt

3. Prepare environment variables for SMTP/IMAP (example shown in the repo's Windows/macOS/Linux guidance). You can create a dotenv file or export variables in your shell, for example:

export SMTP_HOST="smtp.yourprovider.com"
export SMTP_PORT="465"
export SMTP_SECURE="true"
export SMTP_USER="your-email@example.com"
export SMTP_PASS="your-app-password"
export IMAP_HOST="imap.yourprovider.com"
export IMAP_PORT="993"
export IMAP_SECURE="true"
export IMAP_USER="your-email@example.com"
export IMAP_PASS="your-app-password"
export DEFAULT_FROM_NAME="Your Name"
export DEFAULT_FROM_EMAIL="your-email@example.com"

4. Run the MCP bridge (the Python script referenced in the config):

# From the repository root, using the same Python interpreter that your environment uses
python bridging_mail_mcp.py

5. If you prefer Cursor integration, configure your MCP in Cursor to point to the bridging_mail_mcp.py script as shown in the README (Windows/macOS/Linux examples).

Notes and tips:

• Ensure your SMTP/IMAP credentials are kept secure and not committed to version control.
• The bridge runs locally and handles all mail operations; no data is forwarded to third-party servers beyond your own SMTP/IMAP providers.
• If you encounter connection errors, verify firewall settings and that the SMTP/IMAP servers accept connections from your environment.
• For Windows, macOS, and Linux, follow the exact path conventions in the README when configuring Cursor MCP, adjusting the user paths to match your environment.
• If you need to change default sender information, update DEFAULT_FROM_NAME and DEFAULT_FROM_EMAIL in the environment variables.
• The MCP interface is designed to be human-readable; when testing, try simple prompts like "list folders" or "send a test email to someone@example.com" to verify basic functionality.