Gmail

The Gmail MCP Server provides a Python-based interface to read, send, and manage Gmail messages across multiple accounts using the MCP framework. It enables programmatic email workflows, including reading conversations, sending messages with attachments, and searching or downloading attachments through a consistent server API.

How to use

You interact with the Gmail MCP Server through an MCP client. Start the server locally to accept MCP requests, then send actions such as reading emails, sending messages, or searching and downloading attachments. The server handles authentication with Gmail accounts via OAuth 2.0 and stores tokens for reuse.

How to install

Prerequisites: you need Python 3.12 or higher. You also require a Google Cloud project with the Gmail API enabled and OAuth 2.0 client credentials. Install Python packages from the project’s package configuration.

Step by step commands to install and prepare the server locally:

# 1) Install dependencies and set up a virtual environment
python -m venv venv
# On Windows
venv\Scripts\activate
# On Unix/MacOS
source venv/bin/activate

# 2) Install the Gmail MCP Server from source
pip install .

Additional setup notes

Configuration and authentication require you to have a client_secret.json in the project root and to generate OAuth tokens for each Gmail account you want to use. The token files are stored locally to enable reuse without re-authenticating.

Starting the server locally uses the Python script that runs the MCP server. You can also run the server inside a Docker container using the provided container configuration.

# Start the server locally (from project root)
python gmail_server.py

# Run the server in a Docker container (example)
docker build -t gmail-mcp-server .
docker run -v $(pwd)/client_secret.json:/app/client_secret.json \
           -v $(pwd)/token_files:/app/token_files gmail-mcp-server

Notes on security and maintenance

Store client_secret.json securely and avoid committing token files to version control. Use environment variables for sensitive information and rotate OAuth credentials periodically. Monitor API usage and set appropriate quotas to prevent unexpected charges or throttling.

Available tools

send_email

Send an email with optional attachments by providing recipient, subject, body, and attachment paths.

search_email

Search Gmail messages with query parameters and options to include conversations.

read_latest_emails

Read the most recent emails for a given account and optionally download attachments.

download_attachments

Download attachments from a specific message or thread to a local directory.