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)
[English Version (README-EN.md)](README-EN.md)
## What is this
This is a mail tool based on MCP (Model Context Protocol) that allows AI models to access email services through a standardized interface.
Simply put, it allows AI assistants to perform various mail operations, such as sending emails, reading inboxes, and handling attachments, without users having to manually enter complex API calls or switch to email clients.
<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**: Get folder list, list emails, advanced search, get email details
- **Email Management**: Mark as read/unread, delete emails, move emails
- **Attachment Management**: View attachment list, download attachments, view attachment content
- **Contact Management**: Get contact list, search contacts
</details>
<details>
<summary><b>Features</b> (Click to expand)</summary>
Here are some core features of the Mail MCP Tool:
- **Advanced Search Function**: Supports complex condition searches such as multiple folders, keywords, date ranges, senders, and recipients
- **Intelligent Contact Management**: Automatically extracts contact information from email history, including contact frequency analysis
- **Content Range Control**: Allows viewing large emails in segments to avoid loading too much content
- **Multiple Email Formats**: Supports sending and displaying plain text and HTML format emails
- **Attachment Handling**: Intelligently identifies attachment types and supports previewing 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 instructions, AI can help you complete all the above operations without manually writing API calls or performing complex operations in email clients.
</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 [Node.js Official Website](https://nodejs.org/)
- Download and install the LTS (Long Term Support) version
- Select the default options during installation, and the installation package will install Node.js and npm at the same time
2. Verify Installation
- After installation, open Command Prompt (CMD) or PowerShell
- Enter the following command to confirm successful installation:
```bash
node --version
npm --version
```
- If the version number is displayed, the installation is successful
3. Install Git (if not already installed)
- Visit [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 [Python Official Website](https://www.python.org/downloads/)
- Download and install Python 3.11 or higher
- **Important**: You must check the "Add Python to PATH" option during installation
- **Restart your computer** after installation 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 Project
```bash
npm run build
```
### 3. Add to Cursor MCP Configuration
Depending on your operating system, follow these steps 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
> - Make sure the path points to the project directory you cloned or unzipped
> - The path should reflect the actual location where you placed the project files
> - **Do not delete the cloned or unzipped folder**, as this will prevent MCP from working properly
</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
> - Make sure the path points to the project directory you cloned or unzipped
> - The path should reflect the actual location where you placed the project files
> - **Do not delete the cloned or unzipped folder**, as this will prevent MCP from working properly
</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
> - Make sure the path points to the project directory you cloned or unzipped
> - The path should reflect the actual location where you placed the project files
> - **Do not delete the cloned or unzipped folder**, as this will prevent MCP from working properly
</details>
### 4. Start Service
After the configuration is complete, restart the Cursor editor, and it will automatically start the MCP service. Then you can start using it.
<details>
<summary>Usage Example (Click to expand)</summary>
You can ask AI to perform the following operations:
- "List my mailbox 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 the details of the email with UID 1234"
- "Download attachments in the email"
</details>
## How it works
<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 mail clients, and uses **Zod** for request validation and type checking.
The main technical components include:
- **SMTP Client**: Responsible for all email sending functions, supporting HTML content and attachments
- **IMAP Client**: Responsible for connecting to the mailbox server to obtain email lists, details, and attachments
- **Email Parser**: Uses **mailparser** to parse complex email formats
- **Content Processing**: Intelligently processes HTML and plain text content, and supports segmented loading of large emails
- **Contact Extraction**: Automatically extracts and organizes contact information from email history
Each mail operation is encapsulated as a standardized MCP tool, receiving structured parameters and returning formatted results. All data is processed to ensure that it is presented in a human-readable format, so that AI models can easily understand the content structure of emails.
</details>
## License
ISC
---
If this project is helpful to you, welcome to give a Star ⭐️ (｡♥‿♥｡)
