Gmail

You can manage Gmail accounts programmatically through a dedicated MCP server that lets you read, send, search, and download emails across multiple Gmail accounts. This server exposes practical endpoints and tooling to automate common email workflows while keeping credentials and tokens secure.

How to use

Using the Gmail MCP Server, you connect your MCP client to the local or remote server to perform typical email tasks. You can send messages (with optional attachments), search for emails with advanced queries, read the latest messages, and download attachments. The server supports handling conversations and real-time monitoring for responsive email automation.

Key workflows you can implement with your MCP client include: sending emails with attachments, searching across multiple Gmail accounts, reading latest emails, and downloading attachments for further processing. Each function is exposed as a tool you can invoke from your MCP client, using the tailored identifiers and parameters provided by the server.

For practical usage, you typically authenticate each Gmail account once and then issue operations through your MCP client. The server maintains per-account context so you can perform cross-account actions from a single workflow.

How to install

Prerequisites include a Python 3.12+ environment and a Google Cloud project with Gmail API enabled. You also need OAuth 2.0 Client ID credentials and the required Python packages as listed in the project configuration.

Install the Gmail MCP Server via Smithery to integrate with Claude Desktop automatically:

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

Concrete setup steps

Clone the repository, set up a Python virtual environment, and install dependencies.

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

Create and activate a virtual environment, then install the Python package in editable/installed mode.

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

pip install .

Google Cloud project setup

Set up a Google Cloud project and obtain OAuth 2.0 credentials for desktop apps. You will download a client configuration file and place it in your project root as client_secret.json.

# Navigate to Google Cloud Console and create a project or select an existing one
# Enable Gmail API for the project
# Create OAuth 2.0 credentials -> OAuth client ID -> Desktop app
# Download the client configuration file

Configuration

Configure per-account identifiers and authentication in your setup. You will specify an email identifier for each Gmail account you add to the server.

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

Starting the server

Run the server locally to begin accepting MCP requests from your client.

python gmail_server.py

Using the built-in tools

The server exposes a set of tools you can call from your MCP client. Practical examples include sending emails, searching emails, reading latest emails, and downloading attachments.

Security considerations

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

Error handling and logs

The server logs diagnostic information to a dedicated log file and the console for easy debugging. Expect detailed error messages that help you identify misconfigurations or authentication issues.

Notes

If you are integrating multiple Gmail accounts, repeat the per-account setup for each account and ensure each email_identifier is unique within the server configuration.

Available tools

send_gmail

Sends an email to a recipient with a subject and body, including optional attachments.

search_email_tool

Searches emails for a given query, with options for max results and threading.

read_latest_emails

Reads the most recent emails for a given account and optionally downloads attachments.

download_email_attachments

Downloads attachments for a specified message or thread, with options to download per-thread contents.