Gmail-mcp-server
A resilient MCP server built with fastMCP for sending emails through Gmail's SMTP server using AI agents. 
Gmail MCP Server
This repository contains a resilient MCP server implementation using fastMCP. The server is designed to send emails via Gmail's SMTP server and supports various methods for attaching files, including:
- Direct File Path: Attach files that exist on the local filesystem.
- URL-Based Attachments: Download files from a given URL and attach them.
- Pre-Staged Attachments: Use attachments stored in a designated directory.
The server is built with resilience in mind, featuring an increased timeout and graceful shutdown handling.
Features
- Gmail SMTP Integration: Sends emails using Gmail’s SMTP server with TLS. ( MAKE SURE YOU HAVE SETUP GMAIL SMTP ON YOUR ACCOUNT AND GENERATE APP password )
- Multiple Attachment Methods:
- Directly from a file path.
- By downloading from a public URL.
- Using pre-staged attachments stored locally.
- Resilient Design: Increased timeout and signal handling for graceful shutdown.
- Environment-Based Configuration: Securely manage your Gmail credentials using environment variables.
Requirements
- Python 3.x
- fastMCP (install via
pip install mcp)
- python-dotenv (install via
pip install python-dotenv)
- requests (install via
pip install requests)
Setup
Clone the Repository:
git clone
cd gmail-mcp-server
Set Up Environment Variables:
Create a .env file in the root directory and add your Gmail SMTP credentials:
[email protected] SMTP_PASSWORD=your_app_password
Note: If you use 2-Step Verification on your Gmail account, you must generate and use an App Password.
OPEN CLAUDE > SETTINGS > MCP > Configure > OPEN claude_desktop_config.json > Paste the file with your path below { "mcpServers": { "gmail-mcp": { "command": "python", "args": ["PATH_TO_gmail_mcp.py"], "host": "127.0.0.1", "port": 5000, "timeout": 30000 } } }
(Optional) Prepare Attachment Directories:
For pre-staged attachments, create a directory named available_attachments in the root. The server will automatically create a temp_attachments directory when downloading files from URLs.
Running the Server: To start the MCP server, run:
python server.py
The server will start on 127.0.0.1:5000 and can be accessed by your MCP clients or agents.
### Installing via Smithery
To install Gmail MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@MaitreyaM/gmail-mcp-server):
```bash
npx -y @smithery/cli install @MaitreyaM/gmail-mcp-server --client claude
Usage Sending Emails
You can send emails using the send_email_tool with the following parameters:
recipient: Email address of the recipient. subject: Email subject. body: Email body text. attachment_path (optional): Direct file path to the attachment. attachment_url (optional): Public URL from which to download the attachment. attachment_name (optional): Filename to use for the attachment (required when using URL-based or pre-staged attachments). Example Scenarios:
Direct File Attachment:
json Copy { "recipient": "[email protected]", "subject": "Hello with attachment", "body": "Please see the attached document.", "attachment_path": "C:\path\to\document.pdf" }
URL-Based Attachment:
json Copy { "recipient": "[email protected]", "subject": "Hello with attachment", "body": "Please see the attached image.", "attachment_url": "https://example.com/image.png", "attachment_name": "image.png" } Pre-Staged Attachment:
Place your file in the available_attachments directory and reference it by name:
json Copy { "recipient": "[email protected]", "subject": "Hello with attachment", "body": "Please see the attached file.", "attachment_name": "document.pdf" } License: This project is licensed under the MIT License.
Contributing: Contributions are welcome! Feel free to open issues or submit pull requests.
Acknowledgments: Built with fastMCP. Inspired by resilient design patterns for server applications.
