Mail

This Mail MCP Server lets an AI agent interact with an email service through a standardized MCP interface. It enables actions like sending emails, reading mail, and managing attachments or contacts without manual API calls or switching to an email client, making AI-assisted email workflows seamless and automated.

How to use

You connect your MCP-enabled client to the Mail MCP Server and start issuing natural language instructions. You can perform common email tasks such as listing folders, viewing the latest messages, sending messages, performing searches, and handling attachments. The server translates your requests into email client actions and returns human-friendly results that you can present to the user.

How to install

Prerequisites you need before installation are Node.js and npm, and Python 3.11 or newer if you plan to use the bridging script locally.

Install Smithery to enable automatic installation of Mail MCP Tool for your desired client.

Clone the project, install dependencies, and build the project locally.

Configure the MCP client to connect to the Mail MCP Server using a local stdio bridge and the required environment settings.

Start the client, restart the editor or runner if needed, and begin issuing email-related commands.

npx -y @smithery/cli install @shuakami/mcp-mail --client claude

git clone https://github.com/shuakami/mcp-mail.git
cd mcp-mail
npm install
npm run build
"""

# Windows Cursor configuration example (mcp.json)

{
  "mcpServers": {
    "mail_mcp": {
      "command": "pythonw",
      "args": [
        "C:/Users/你的用户名/mcp-mail/bridging_mail_mcp.py"
      ],
      "env": {
        "SMTP_HOST": "smtp.qq.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "SMTP_USER": "your.email@qq.com",
        "SMTP_PASS": "your-app-specific-password",
        "IMAP_HOST": "imap.qq.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "IMAP_USER": "your.email@qq.com",
        "IMAP_PASS": "your-app-specific-password",
        "DEFAULT_FROM_NAME": "Your Name",
        "DEFAULT_FROM_EMAIL": "your.email@qq.com"
      }
    }
  }
}

{
  "mcpServers": {
    "mail_mcp": {
      "command": "pythonw",
      "args": [
        "/Users/你的用户名/mcp-mail/bridging_mail_mcp.py"
      ]
    }
  }
}

{
  "mcpServers": {
    "mail_mcp": {
      "command": "pythonw",
      "args": [
        "/home/你的用户名/mcp-mail/bridging_mail_mcp.py"
      ]
    }
  }
}

Additional sections

Notes on configuration and usage follow in the next sections. You will configure a local bridge so the MCP client talks to your email service via the bridging script. The following environment variables are used to connect to your SMTP/IMAP servers and to set the default sender information. Ensure you provide valid credentials and adjust hostnames and ports to match your email provider.

Configuration and security

All email operations are performed locally by the bridge script. No sensitive data is sent to external servers beyond your own email provider. Keep your credentials secure and avoid sharing your bridge configuration. Use strong application-specific passwords when required by your email service.

Examples of typical commands you can perform

List your email folders, fetch the latest messages, search for emails containing a keyword, read a specific email by UID, download attachments, or manage sender/recipient contacts. You can also set read/unread status, move messages between folders, and extract contact information from history.

Available tools

send_email

Send an email with plain text or HTML content and optional attachments.

list_folders

Retrieve the list of mail folders in your account.

list_emails

List emails within a folder with optional filtering and pagination.

search_emails

Perform advanced searches across folders using keywords, dates, and sender/recipient filters.

get_email

Get detailed information for a specific email by UID.

download_attachment

Download an attachment from a specific email.

mark_read

Mark one or more emails as read or unread.

delete_email

Delete emails from a folder.

move_email

Move emails between folders.

list_contacts

Retrieve contact lists or search for contacts from email history.