Gmail Sender MCP

🚀 Gmail Sender MCP Server

A Model Context Protocol (MCP) server that allows Claude and other AI assistants to send emails via the Gmail API. This version focuses solely on providing email sending functionality.

🚀 Quick Start

The project creates an MCP server enabling AI assistants to:

• Send new emails
• Reply to existing emails

It's designed to be lightweight and easy to set up, using the Gmail API for email operations.

✨ Features

This MCP server empowers AI assistants with the following capabilities:

• Send new emails
• Reply to existing emails

📦 Installation

Prerequisites

• Python 3.8 or higher
• A Google Cloud account with the Gmail API enabled
• Docker (optional, for containerized deployment)

Setup Instructions

1. Create a Google Cloud project and enable the Gmail API

1. Go to the Google Cloud Console.
2. Create a new project or select an existing one.
3. Navigate to "APIs & Services" > "Library" in the sidebar.
4. Search for the "Gmail API" and enable it.
5. Go to "APIs & Services" > "Credentials".
6. Click "Create credentials" and select "OAuth client ID".
7. For the application type, choose "Desktop app".
8. Name your OAuth client.
9. Click "Create".
10. Download the generated credentials JSON file.

2. Prepare your environment

Clone this repository:

git clone https://github.com/abhishekloiwal/gmail-sender-mcp.git
cd gmail-sender-mcp

Install the dependencies:

pip install -r requirements.txt

3. Set up your credentials

1. Rename the downloaded credentials file to credentials.json and place it in the project root directory.
2. Run the helper script to obtain the refresh token:

python get_refresh_token.py

3. Complete the authentication flow in your browser.
4. Copy the refresh token displayed in the terminal.
5. Create a .env file based on the example:

cp .env.example .env

6. Edit the .env file and fill in your credentials:

GMAIL_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=your-client-secret
GMAIL_REFRESH_TOKEN=your-refresh-token
GMAIL_USER_EMAIL=your-email@gmail.com

4. Run the MCP server

python gmail_sender.py

The server will start and listen for connections.

Docker Deployment

You can also run the server in a Docker container:

Build and run with Docker

docker build -t gmail-sender-mcp .
docker run -d --name gmail-sender-mcp --env-file .env gmail-sender-mcp

Or use Docker Compose

docker-compose up -d

💻 Usage Examples

Basic Usage

To use this MCP server with an AI assistant:

1. Run the MCP server.
2. Connect your AI assistant to the MCP server (specific steps depend on your AI platform).

The MCP server provides the following tools:

send_email tool

Send a new email. Parameters:

• to: Recipient's email address
• subject: Email subject line
• body: Email body content (supports HTML format)

reply_to_email tool

Reply to an existing email. Parameters:

• email_id: ID of the email to reply to
• body: Reply content (supports HTML format)

Advanced Usage

Here's an example of using the send_email tool:

from gmail_sender import GmailSender

# Initialize the Gmail sender
gmail = GmailSender(
    client_id='your-client-id.apps.googleusercontent.com',
    client_secret='your-client-secret',
    refresh_token='your-refresh-token',
    user_email='your-email@gmail.com'
)

# Send an email
gmail.send_email(
    to='recipient@example.com',
    subject='Test Email',
    body='This is a test email.'
)

🔧 Technical Details

Environment Variables

Here are the environment variables that might be used in the .env file and their meanings:

GMAIL_CLIENT_ID: Gmail OAuth client ID
GMAIL_CLIENT_SECRET: Gmail OAuth client secret
GMAIL_REFRESH_TOKEN: Gmail refresh token
GMAIL_USER_EMAIL: Google account email address from which emails will be sent
SMTP_SERVER: SMTP server address (default is smtp.gmail.com)
SMTP_PORT: SMTP port (default is 587)

Error Handling

When using the Gmail API, you might encounter the following errors:

1. InvalidGrantError: The refresh token is invalid or has expired.
2. RateLimitExceeded: You've exceeded the Gmail API quota limits.
3. PermissionDenied: You lack the necessary permissions.

Ensure your credentials are valid and that the correct API is enabled in your Google Cloud project.

📄 License

No license information provided in the original document.

⚠️ Important Note

• Keep the .env file secure and never commit it to version control.
• The refresh token grants permission to send emails, so treat it like a password.
• If you're concerned about security, consider using a dedicated Google account for this integration.

💡 Usage Tip

• For authentication errors, make sure the credentials in the .env file are correct.
• For "Module not found" errors, check if all dependencies are correctly installed in your Python environment.
• If you encounter Gmail API quota limits, contact Google Cloud support to increase the quota.