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

Related MCP server: Systemprompt MCP Gmail Server

Prerequisites

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

1. Python 3.12 or higher

2. Google Cloud Project with Gmail API enabled

3. OAuth 2.0 Client ID credentials

4. Required Python packages (specified in pyproject.toml)

Installation

Installing via Smithery

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

1. Clone the repository:

2. Create and activate a virtual environment:

3. Install dependencies:

Running on Ubuntu

1. Install Python 3.12 and create a virtual environment if you haven't already:

   sudo apt install python3.12 python3.12-venv -y python3.12 -m venv venv source venv/bin/activate

2. Place your downloaded client_secret.json in the project root.

3. Generate an OAuth token for the Gmail account you want to use. Copy the URL printed by the script into a web browser and complete the sign-in process:

   python gmail_token_creator.py

4. Start the server:

   python gmail_server.py

Setup Google Cloud Project

1. Go to the Google Cloud Console

2. Create a new project or select an existing one

3. Enable the Gmail API for your project

4. 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

5. Rename the downloaded file to client_secret.json and place it in the project root directory

Configuration

1. Set up email identifiers in gmail_token_creator.py:

2. Run the token creator to authenticate your Gmail accounts:

The script prints an authorization URL. Copy this URL into your web browser, complete the Google consent flow, and copy the verification code back into the terminal if prompted. A token file will be created inside token_files/ for future use.

3. 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

Running with Docker

You can also build a container image using the provided Dockerfile:

The container runs the same server and stores authentication tokens in the token_files directory on the host so they persist between runs.

Available Tools

1. Send Email:

2. Search Emails:

3. Read Latest Emails:

4. Download Attachments:

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

1. Fork the repository

2. Create a feature branch

3. Commit your changes

4. Push to the branch

5. Create a Pull Request

License

Apachelicense2.0

Support

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