Content
# Mail MCP Tool
[](https://opensource.org/licenses/ISC)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://github.com/shuakami/mcp-mail)
[](https://smithery.ai/server/@shuakami/mcp-mail)
[中文版本 (README-CN.md)](README-CN.md)
## What is this
This is an email tool based on MCP (Model Context Protocol) that allows AI models to access email services through a standardized interface.
In simple terms, it enables AI assistants to perform various email operations, such as sending emails, reading inboxes, and handling attachments, without requiring users to manually input complex API calls or switch to an email client.
<details>
<summary><b>Supported Features</b> (click to expand)</summary>
- **Email Sending**: Plain text emails, HTML emails, emails with attachments, bulk emails
- **Email Receiving and Querying**: Retrieve folder lists, list emails, advanced search, get email details
- **Email Management**: Mark as read/unread, delete emails, move emails
- **Attachment Management**: View attachment lists, download attachments, view attachment content
- **Contact Management**: Retrieve contact lists, search for contacts
</details>
<details>
<summary><b>Feature Highlights</b> (click to expand)</summary>
Here are some core features of the Mail MCP tool:
- **Advanced Search Functionality**: Supports complex condition searches across multiple folders, keywords, date ranges, senders, recipients, etc.
- **Intelligent Contact Management**: Automatically extracts contact information from email history, including frequency analysis
- **Content Range Control**: Allows segmented viewing of large emails to avoid loading excessive content
- **Multiple Email Formats**: Supports sending and displaying both plain text and HTML format emails
- **Attachment Handling Capability**: Smartly identifies attachment types, supporting previews of different types of attachments such as text and images
- **Safe and Reliable**: Processes all email operations locally, without forwarding sensitive information through third-party servers
With simple natural language commands, AI can assist you in completing all of the above operations without the need to manually write API calls or perform complex actions in an email client.
</details>
## Quick Start
### 0. Environment Preparation
<details>
<summary>If you have not used Node.js before (click to expand)</summary>
1. Install Node.js and npm
- Visit the [Node.js official website](https://nodejs.org/)
- Download and install the LTS (Long Term Support) version
- Choose the default options during installation; the installer will install both Node.js and npm
2. Verify the installation
- After installation, open Command Prompt (CMD) or PowerShell
- Enter the following commands to confirm the installation was successful:
```bash
node --version
npm --version
```
- If version numbers are displayed, the installation was successful
3. Install Git (if not already installed)
- Visit the [Git official website](https://git-scm.com/)
- Download and install Git
- Use the default options during installation
4. Install Python 3.11 or higher (required)
- Visit the [Python official website](https://www.python.org/downloads/)
- Download and install Python 3.11 or higher
- **Important**: Make sure to check the "Add Python to PATH" option during installation
- After installation, **restart your computer** to ensure the environment variables take effect
</details>
### Installing via Smithery
To install Mail MCP Tool for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@shuakami/mcp-mail):
```bash
npx -y @smithery/cli install @shuakami/mcp-mail --client claude
```
### 1. Clone and Install
```bash
git clone https://github.com/shuakami/mcp-mail.git
cd mcp-mail
npm install
npm run build
```
### 2. Build the Project
```bash
npm run build
```
### 3. Add to Cursor MCP Configuration
Depending on your operating system, follow the steps below to configure MCP:
<details>
<summary><b>Windows Configuration</b> (click to expand)</summary>
1. In Cursor, open or create the MCP configuration file: `C:\\Users\\your_username\\.cursor\\mcp.json`
- Note: Please replace `your_username` with your Windows username.
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"mail-mcp": {
"command": "pythonw",
"args": [
"C:/Users/your_username/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"
}
}
}
}
```
> ⚠️ **Please Note**:
> - Replace `your_username` with your Windows username.
> - Ensure the path correctly points to the directory where you cloned or extracted the project.
> - The path should reflect the actual location where you placed the project files.
> - **Do not delete the cloned or extracted folder**, as this will cause MCP to malfunction.
</details>
<details>
<summary><b>macOS Configuration</b> (click to expand)</summary>
1. In Cursor, open or create the MCP configuration file: `/Users/your_username/.cursor/mcp.json`
- Note: Please replace `your_username` with your macOS username.
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"mail-mcp": {
"command": "pythonw",
"args": [
"/Users/your_username/mcp-mail/bridging_mail_mcp.py"
]
}
}
}
```
> ⚠️ **Please Note**:
> - Replace `your_username` with your macOS username.
> - Ensure the path correctly points to the directory where you cloned or extracted the project.
> - The path should reflect the actual location where you placed the project files.
> - **Do not delete the cloned or extracted folder**, as this will cause MCP to malfunction.
</details>
<details>
<summary><b>Linux Configuration</b> (click to expand)</summary>
1. In Cursor, open or create the MCP configuration file: `/home/your_username/.cursor/mcp.json`
- Note: Please replace `your_username` with your Linux username.
2. Add or modify the configuration as follows:
```json
{
"mcpServers": {
"mail-mcp": {
"command": "pythonw",
"args": [
"/home/your_username/mcp-mail/bridging_mail_mcp.py"
]
}
}
}
```
> ⚠️ **Please Note**:
> - Replace `your_username` with your Linux username.
> - Ensure the path correctly points to the directory where you cloned or extracted the project.
> - The path should reflect the actual location where you placed the project files.
> - **Do not delete the cloned or extracted folder**, as this will cause MCP to malfunction.
</details>
### 4. Start the Service
After configuration, restart the Cursor editor, and it will automatically start the MCP service. Then you can begin using it.
<details>
<summary>Usage Examples (click to expand)</summary>
You can ask the AI to perform the following actions:
- "List my email folders"
- "Show the latest 5 emails in the inbox"
- "Send an email with the subject 'Test Email' to example@example.com"
- "Search for emails containing the keyword 'invoice'"
- "View details of the email with UID 1234"
- "Download attachments from the email"
</details>
## Working Principle
<details>
<summary>Technical Implementation Details (Click to Expand)</summary>
This tool is implemented based on the **MCP (Model Context Protocol)** standard, serving as a bridge between AI models and email services. It uses **nodemailer** and **node-imap** as the underlying email clients, and performs request validation and type checking through **Zod**.
The main technical components include:
- **SMTP Client**: Responsible for all email sending functionalities, supporting HTML content and attachments
- **IMAP Client**: Responsible for connecting to the email server, retrieving email lists, details, and attachments
- **Email Parser**: Uses **mailparser** to parse complex email formats
- **Content Processing**: Intelligently handles HTML and plain text content, supporting segmented loading of large emails
- **Contact Extraction**: Automatically extracts and organizes contact information from email history
Each email operation is encapsulated as a standardized MCP tool, receiving structured parameters and returning formatted results. All data is processed to ensure it is presented in a human-readable format, allowing AI models to easily understand the content structure of emails.
</details>
## License
ISC
---
If this project has been helpful to you, feel free to give it a Star ⭐️ (｡♥‿♥｡)
