Gmail MCP Server

🚀 Gmail-MCP-Server

A resilient MCP server built with fastMCP for sending emails via Gmail's SMTP server and handling file attachments with an AI agent.

🚀 Quick Start

This repository contains a resilient MCP implementation built with fastMCP. The server is designed to send emails via Gmail's SMTP server and supports several methods for attaching files:

• Direct file path: Attach files that exist in the local file system.
• URL-based attachment: Download and attach files from a specified URL.
• Pre-stored attachments: Use attachments stored in a specific directory.

The server is designed with resilience in mind, featuring increased timeout settings and graceful shutdown handling.

✨ Features

• Gmail SMTP integration: Send emails via Gmail's SMTP server over TLS. (Ensure you have set up Gmail SMTP on your account and generated an app password.)
• Multiple attachment methods:
  • Attach directly from a file path.
  • Download and process files from public URLs.
  • Use pre-stored local attachments.
• Resilient design: Increased timeout settings and signal handling for graceful shutdown.
• Environment variable-based configuration: Securely manage Gmail credentials using environment variables.

📦 Installation

Prerequisites

• Python 3.x
• fastMCP (Install via pip install mcp)
• python-dotenv (Install via pip install python-dotenv)
• requests (Install via pip install requests)

Steps

1. Clone the repository:

git clone <remote repository URL>
cd gmail-mcp-server

2. Set up environment variables: Create a .env file in the root directory and add your Gmail SMTP credentials:

SMTP_USERNAME=your.email@gmail.com 
SMTP_PASSWORD=your_app_password

⚠️ Important Note

If you have two-step verification enabled on your Gmail account, you must generate and use an app password.

3. Configure OPEN CLAUDE: OPEN CLAUDE > Settings > MCP > Configuration > OPEN claude_desktop_config.json > Paste the file into the following path:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "python",
      "args": ["PATH_TO_gmail-mcp.py"],
      "port": 5005
    }
  }
}

Replace PATH_TO_gmail-mcp.py with the actual script path.

4. Install fastMCP using pip:

pip install mcp

5. Run the server:

python your_script_name.py

💻 Usage Examples

Basic Usage

1. Direct file attachment

In a Python script, attach directly from a file path:

from mcp import Client

client = Client('localhost', 5005)
client.send_email_with_attachment('to@example.com', 'Subject', 'Body', '/path/to/file.txt')

2. URL-based attachment

Download and attach a file via a specified URL:

from mcp import Client

client = Client('localhost', 5005)
client.send_email_with_url_attachment('to@example.com', 'Subject', 'Body', 'http://example.com/file.txt')

3. Pre-stored attachment

Process using a pre-stored attachment:

from mcp import Client

client = Client('localhost', 5005)
client.send_email_with_pre_attached_file('to@example.com', 'Subject', 'Body', '/path/to/pre_attachment.txt')