MCP Email Server

What is MCP Email Server about?

MCP Email Server provides an MCP‑based interface that allows large language models to compose and dispatch emails, attach files, and locate attachment files in a given folder through pattern matching.

How to use MCP Email Server?

1. Install required Python packages:

   pip install pydantic python-dotenv
   

2. Create an email.json configuration file that maps email domains to their SMTP servers and ports.
3. Set environment variables SENDER (the email address) and PASSWORD (app‑specific password or SMTP password).
4. Run the server, optionally specifying the attachment directory:

   python -m mcp_email_server --dir /path/to/attachment/directory
   

5. In your LLM or Claude.app configuration, reference the server under mcpServers.email with the appropriate command and arguments.

Key features of MCP Email Server

• Multiple recipient support
• Attachment handling with type whitelist (doc, pdf, zip, jpg, etc.)
• Pattern‑based file search within a user‑specified directory
• Secure SMTP transmission (TLS)
• Compatibility with major providers: Gmail, Outlook, Yahoo, QQ, NetEase 126, etc.

Use cases of MCP Email Server

• Automated report distribution from AI agents
• Context‑aware email drafting with attached analysis results
• File lookup for sending relevant documents based on keyword patterns
• Integration with Claude or other LLM platforms for hands‑free communication workflows

FAQ from the MCP Email Server

Q: Do I need an app‑specific password for Gmail? A: Yes, Gmail requires an app password or OAuth token for third‑party SMTP access.

Q: Which attachment types are allowed? A: Documents (doc, docx, pdf, etc.), archives (zip, rar, 7z), text files (txt, csv, json), images (jpg, png, gif), and markdown files.

Q: How do I change the SMTP server for a custom domain? A: Add an entry to email.json with the domain suffix, server address, and port.

Q: Can I run the server in a virtual environment? A: Absolutely; just activate the environment before installing dependencies and launching the server.

MCP Email Server

A Model Context Protocol server that provides email functionality. This server enables LLMs to compose and send emails, as well as search for attachments within specified directories.

Features

• Send emails with multiple recipients
• Support for email attachments
• Search for files in directories based on pattern matching
• Secure email transmission using SMTP

Available Tools

• send_email - Sends emails based on the provided subject, body, and receiver.

  • receiver (array of strings, required): List of recipient email addresses
  • body (string, required): The main content of the email
  • subject (string, required): The subject line of the email
  • attachments (array of strings or string, optional): Email attachments (filenames)

• search_attachments - Searches for files in a specified directory that match a given pattern.

  • pattern (string, required): The text pattern to search for in file names

Prompts

• send_email

  • Send an email with optional attachments
  • Arguments:
    • receiver (required): The list of recipient email addresses
    • body (required): The main content of the email
    • subject (required): The subject line of the email
    • attachments (optional): Email attachments

• search_attachments

  • Search for files matching a pattern
  • Arguments:
    • pattern (required): The text pattern to search for in file names

Installation

Using pip

Install the required dependencies:

pip install pydantic python-dotenv

Email Configuration

An email.json file with SMTP server configurations:

[
  {
    "domain": "@gmail.com",
    "server": "smtp.gmail.com", 
    "port": 587
  },
  {
    "domain": "@outlook.com",
    "server": "smtp.office365.com",
    "port": 587
  },
  {
    "domain": "@yahoo.com",
    "server": "smtp.mail.yahoo.com",
    "port": 587
  }
]

Usage

Running the Server

Start the MCP Email Server with:

python -m mcp_email_server (--dir /path/to/attachment/directory)

Configure for Claude.app

Add to your Claude settings:

Conda

{
  "mcpServers": {
    "email": {
      "command": "D:\\conda\\envs\\mcp\\python.exe",
      "args": [
        "C:\\Users\\YourUserName\\Desktop\\servers\\src\\email\\src\\mcp_server_email",
        "--dir",
        "C:\\Users\\YourUserName\\Desktop"
      ],
      "env": {
        "SENDER": "2593666979q@gmail.com",
        "PASSWORD": "tuogk......."
      }
    }
  }
}

UV

{
  "mcpServers": {
    "email": {
      "command": "uv",
      "args": [
        "~\\servers\\src\\email\\src\\mcp_server_email",
        "--dir",
        "C:\\Users\\YourUserName\\Desktop"
      ],
      "env": {
        "SENDER": "2593666979q@gmail.com",
        "PASSWORD": "tuogk......."
      }
    }
  }
}

Security Notes

• For Gmail and other services, you may need to use an app-specific password
• The server supports a limited set of attachment file types for security reasons

Supported File Types

The server supports the following attachment file types:

• Documents: doc, docx, xls, xlsx, ppt, pptx, pdf
• Archives: zip, rar, 7z, tar, gz
• Text files: txt, log, csv, json, xml
• Images: jpg, jpeg, png, gif, bmp
• Other: md

Example Usage

Sending an Email

{
  "receiver": ["recipient@example.com"],
  "subject": "Test Email from MCP Server",
  "body": "This is a test email sent via the MCP Email Server.",
  "attachments": ["document.pdf", "image.jpg"]
}

Searching for Attachments

{
  "pattern": "report"
}

Contributing

We encourage contributions to help expand and improve the MCP Email Server. Whether you want to add new tools, enhance existing functionality, or improve documentation, your input is valuable.

For examples of other MCP servers and implementation patterns, see: https://github.com/modelcontextprotocol/servers

Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make the MCP Email Server even more powerful and useful.

License

MCP Email Server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License.