Gmail Imap MCP

🚀 Gmail IMAP Management Console Protocol (MCP) Server

Gmail IMAP MCP Server is a command-line tool for managing and operating Gmail emails via the IMAP protocol. It supports the following features:

• Retrieve unread emails
• Fetch specific emails
• Send new emails
• Create and manage labels
• Move emails to different labels
• Download attachments

🚀 Quick Start

📦 Installation

Install Dependencies

pip install gmail-imap-mcp-server

Configuration Steps

1. Create a config folder in the project root directory.
2. Place client_secret.json into the config folder.
3. Run the authentication command:

   python -m gmail_imap_mcp_server authenticate
   

✨ Features

Core Functions

• Retrieve Unread Emails

python -m gmail_imap_mcp_server list-unread-emails [--label LABEL] [--limit LIMIT]

• Fetch Specific Emails

python -m gmail_imap_mcp_server get-email <email_id>

• Send New Emails

python -m gmail_imap_mcp_server send-email --to TO_EMAIL --subject SUBJECT --body BODY

Label Management

• Create a Label

python -m gmail_imap_mcp_server create-label LABEL_NAME

• Delete a Label

python -m gmail_imap_mcp_server delete-label LABEL_NAME

• Rename a Label

python -m gmail_imap_mcp_server rename-label OLD_NAME NEW_NAME

Email Operations

• Move an Email

python -m gmail_imap_mcp_server move-email <email_id> TARGET_LABEL

Attachment Management

• Download an Attachment

python -m gmail_imap_mcp_server download-attachment <attachment_id> --output OUTPUT_PATH

💻 Usage Examples

Basic Usage

# Example 1: Retrieve unread emails
$ python -m gmail_imap_mcp_server list-unread-emails --label Inbox

Output:

Email ID: 12345, From: boss@example.com, Subject: Q4 Report Due
Email ID: 67890, From: client@example.com, Subject: Project Update

# Example 2: Send an email
$ python -m gmail_imap_mcp_server send-email --to team@example.com --subject "Meeting Tomorrow" --body "Please join the meeting at 2 PM."

Advanced Usage

# Get email content
$ python -m gmail_imap_mcp_server get-email m1@abc.xyz

Output:

From: boss@example.com
To: me@example.com
Subject: Q4 Report
Body: Please review the attached report.

Code Examples

Basic Usage

# Simple email sending
from gmail_imap_mcp_server import GmailIMAPMCPClient

client = GmailIMAPMCPClient()
client.send_email(
    to="team@example.com",
    subject="Meeting Tomorrow",
    body="Please join the meeting at 2 PM."
)

Advanced Usage

# Send an email with attachments
import os
from gmail_imap_mcp_server import GmailIMAPMCPClient

client = GmailIMAPMCPClient()
client.send_email(
    to="receiver@example.com",
    subject="Document Attached",
    body="Please find attached the document.",
    attachments=[os.path.abspath("document.pdf")]
)

Troubleshooting

Problem 1: Unable to Connect to Gmail

$ python -m gmail_imap_mcp_server authenticate

Follow the prompts to enter your Gmail account information.

Problem 2: Email Not Found

• Check if the email ID is correct.
• Ensure that the target label exists.

Security Considerations

⚠️ Important Note

• Avoid using the --noauth_local_webserver flag for authentication.
• Do not store credentials in plain text in a production environment.
• Regularly update your Gmail password.

📄 License

This project is licensed under the MIT License.
See LICENSE for more details.

Contributors

• Zhang San (zhangsan@example.com)
• Li Si (lisi@example.com)

Gmail IMAP MCP Server provides you with powerful and flexible email management capabilities to help you efficiently handle Gmail emails.