Gmail

This Gmail MCP Server provides a programmable interface to interact with Gmail accounts via the MCP framework. It supports reading emails, sending messages (with attachments), searching emails with advanced queries, downloading attachments, and handling conversations and threads. The server is designed to work with multiple Gmail accounts, storing OAuth tokens locally so you can manage several accounts from a single MCP instance. Available tools include sending emails, searching mail, reading latest messages, and downloading attachments, all accessible through asynchronous function calls in your MCP client.

To use the tools, first ensure your environment has a configured Gmail OAuth client secret (client_secret.json) and the required token files are generated for each account. Start the Python server (gmail_server.py). Then, via your MCP client, call the provided utilities, specifying the target email identifier for the Gmail account you want to operate on and the relevant parameters (recipient, subject, body, attachments, or search queries). For example, you can send an email with an attachment, search your mailbox with a query like from:someone@example.com, or read the latest emails and optionally download attachments.

The server exposes key capabilities:

• Send Email: compose and send messages with optional attachments using send_gmail.
• Search Emails: perform Gmail searches with queries and return matching messages via search_email_tool.
• Read Latest Emails: fetch recent messages and optionally download their attachments with read_latest_emails.
• Download Attachments: download attachments for a given message or across a thread using download_email_attachments.

If you run into token or permission issues, verify that client_secret.json is placed at the project root, that the Gmail API is enabled in your Google Cloud project, and that you have completed the OAuth flow to generate token files inside token_files/.

Prerequisites: - Python 3.12 or higher - Google Cloud Project with Gmail API enabled - OAuth 2.0 Client ID credentials (client_secret.json) - Internet access to install dependencies

1. Create and activate a virtual environment (recommended):

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

2. Install the Gmail MCP server package in editable or local mode:

pip install .  # from the repository root

3. Ensure your Google credentials are in place:

• Place client_secret.json in the project root
• Run the token creation script to generate tokens for each Gmail account (as described in the README):

python gmail_token_creator.py

4. Start the server:

python gmail_server.py

5. (Optional) Build and run with Docker:

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

Tips and common considerations:

• Store client_secret.json securely and do not commit it to version control. Use environment variables to override sensitive paths when running in production.
• The server writes logs to gmail_mcp.log and supports both file and console logging; review logs for debugging.
• If you run multiple Gmail accounts, repeat the token generation process for each account and ensure tokens are stored under token_files/ with distinct identifiers.
• When running in Docker, ensure the token_files directory on the host is mounted to persist tokens across restarts.
• Ensure the Gmail API quota limits are appropriate for your expected usage; monitor API usage in your Google Cloud Console.
• For security, rotate OAuth credentials periodically and limit OAuth scopes to what is strictly necessary for your use case.