mcp-email-client 0.1.7

A Model Context Protocol (MCP) server for sending and receiving emails, supporting IMAP/SMTP, with display name, reply, robust error handling, and full attachment support.

MCP Email Client

A Model Context Protocol (MCP) server for sending and receiving emails, supporting IMAP/SMTP, with display name, reply, robust error handling, and full attachment support.

Features

• Send emails (with display name and attachment support)
• List inbox/sent emails (brief info, attachment count)
• Read email details by UID (auto-save and list attachments)
• Reply to emails (auto set headers, display name, attachments)
• Environment variable based configuration
• Robust error handling and IMAP/SMTP compatibility

Example JSON config for MCP/Claude/Inspector

This format is suitable for use with Claude Desktop, MCP Inspector, or any MCP client that supports multi-server JSON configuration:

{
  "mcpServers": {
    "mcp-email-client": {
      "command": "uvx",
      "args": [
        "mcp-email-client"
      ],
      "env": {
        "MAIL_USER_NAME": "[e-mail]",
        "MAIL_PASS_WORD": "yourpassword",
        "MAIL_SMTP_ADDR": "smtp.example.com:465",
        "MAIL_IMAP_ADDR": "imap.example.com:993",
        "MAIL_FROM_NAME": "Your Name",
        "MAIL_FROM_ADDR": "[e-mail]",
        "MAIL_SAVE_PATH": "/absolute/path/to/attachments"
      }
    }
  }
}

• You can add multiple servers under mcpServers.
• This config can be loaded directly by Claude Desktop, MCP Inspector, or compatible tools.

Environment Variables

Name	Description	Example
MAIL_USER_NAME	Email account (login username)	[e-mail]
MAIL_PASS_WORD	Email account password/app token	yourpassword
MAIL_SMTP_ADDR	SMTP host:port	smtp.example.com:465
MAIL_IMAP_ADDR	IMAP host:port	imap.example.com:993
MAIL_FROM_ADDR	(Optional) From email address	[e-mail]
MAIL_FROM_NAME	(Optional) From display name	Alice
MAIL_SAVE_PATH	(Optional) Path to save attachments	/absolute/path/to/dir

Installation

uv pip install fastmcp
# or
pip install fastmcp

Usage

1. Set environment variables (see above)
2. Run the server:

python server.py

API Endpoints (Tools)

send_email

Send an email, with optional attachments.

• Args:
  • to: Recipient email address
  • subject: Email subject
  • content: Email body (plain text)
  • attachments: List of absolute file paths to attach (optional)
• Returns: { "success": bool, "message": str }

reply_email

Reply to an email, with optional attachments.

• Args:
  • uid: UID of the original email to reply to
  • subject: Email subject
  • content: Email body (plain text or HTML)
  • attachments: List of absolute file paths to attach (optional)
• Returns: { "success": bool, "message": str }

list_inbox / list_sent

List inbox or sent emails (brief info, attachment count).

• Args:
  • limit: Maximum number of emails to return (default 10)
  • start: Start index (0-based, from the latest email)
• Returns: { "emails": [ { "uid", "subject", "snippet", "date", "seen", "attachment" } ] }
  • attachment: Number of attachments in the email

read_email

Read full details of an email by UID, auto-save and list attachments.

• Args:
  • uid: UID of the email
• Returns: { "uid", "message_id", "from", "to", "subject", "date", "seen", "in_reply_to", "references", "snippet", "attachments" }
  • attachments: List of all attachment filenames (auto-saved to MAIL_SAVE_PATH/uid/ if MAIL_SAVE_PATH is set)

Example .env

MAIL_USER_NAME=[e-mail]
MAIL_PASS_WORD=yourpassword
MAIL_SMTP_ADDR=smtp.example.com:465
MAIL_IMAP_ADDR=imap.example.com:993
MAIL_FROM_NAME=Your Name
MAIL_FROM_ADDR=[e-mail]
MAIL_SAVE_PATH=/absolute/path/to/attachments

FAQ

• Q: Why do I get 'Email content is empty'?
  • A: The UID may not exist, or the email was deleted/moved. Make sure to use a valid UID from list_inbox/list_sent.
• Q: How to set display name?
  • A: Set MAIL_FROM_NAME in your environment variables.
• Q: How to send HTML email?
  • A: Just include HTML tags in content, the server will auto-detect and set the correct MIME type.
• Q: How to send attachments?
  • A: Pass a list of absolute file paths to the attachments parameter in send_email or reply_email.
• Q: How to auto-save received attachments?
  • A: Set MAIL_SAVE_PATH. All attachments will be saved to MAIL_SAVE_PATH/uid/ when reading emails.

License

MIT