Gmail MCP Server

A powerful and flexible Gmail integration server built using the MCP (Message Control Protocol) framework. This server provides a robust interface to interact with Gmail APIs, offering functionality for reading, sending, and managing emails programmatically.

Features

Read emails from multiple Gmail accounts
Send emails with attachments
Search emails with advanced query options
Download email attachments
Handle email conversations and threads
Real-time email monitoring
Support for multiple Gmail accounts

Prerequisites

Before running the Gmail MCP server, ensure you have the following:

Python 3.12 or higher
Google Cloud Project with Gmail API enabled
OAuth 2.0 Client ID credentials
Required Python packages (specified in pyproject.toml)

Installation

Installing via Smithery

To install Gmail Integration Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @Quantum-369/Gmail-mcp-server --client claude

Clone the repository:

git clone <your-repository-url>
cd gmail-mcp-server

Create and activate a virtual environment:

python -m venv venv
# On Windows
venv\Scripts\activate
# On Unix/MacOS
source venv/bin/activate

Install dependencies:

pip install .

Setup Google Cloud Project

Go to the Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API for your project
Create OAuth 2.0 credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose "Desktop app" as application type
- Download the client configuration file
Rename the downloaded file to client_secret.json and place it in the project root directory

Configuration

Set up email identifiers in gmail_token_creator.py:

email_identifier = 'your.email@gmail.com'  # Change this for each account

Run the token creator to authenticate your Gmail accounts:

python gmail_token_creator.py

Repeat the process for each Gmail account you want to integrate

Server Structure

gmail_server.py: Main MCP server implementation
gmail_api.py: Gmail API interaction functions
google_apis.py: Google API authentication utilities
Supporting files:
- read_emails.py: Email reading functionality
- search_emails.py: Email search functionality
- send_emails.py: Email sending functionality

Usage

Starting the Server

python gmail_server.py

Available Tools

Send Email:

await send_gmail(
    email_identifier="your.email@gmail.com",
    to="recipient@example.com",
    subject="Test Subject",
    body="Email body content",
    attachment_paths=["path/to/attachment"]
)

Search Emails:

await search_email_tool(
    email_identifier="your.email@gmail.com",
    query="from:someone@example.com",
    max_results=30,
    include_conversations=True
)

Read Latest Emails:

await read_latest_emails(
    email_identifier="your.email@gmail.com",
    max_results=5,
    download_attachments=False
)

Download Attachments:

await download_email_attachments(
    email_identifier="your.email@gmail.com",
    msg_id="message_id",
    download_all_in_thread=False
)

Security Considerations

Store client_secret.json securely and never commit it to version control
Keep token files secure and add them to .gitignore
Use environment variables for sensitive information
Regularly rotate OAuth credentials
Monitor API usage and set appropriate quotas

Error Handling

The server includes comprehensive error handling and logging:

Logs are written to gmail_mcp.log
Both file and console logging are enabled
Detailed error messages for debugging

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

Apachelicense2.0

Support

For issues and feature requests, please use the GitHub issue tracker.