Advanced Email Management Utility (GMAYL-CTL-PRO)

This utility serves as a powerful Model Context Protocol (MCP) intermediary, facilitating seamless, natural-language interaction with the Gmail ecosystem via a Python-based server backend. It grants AI agents unparalleled control over electronic mail operations.

🌟 Core Functionality Set

✉️ Message Operations Suite

Transmit correspondence, fully specifying subject, body text, and recipients.
Fetch and decode email contents, retrieving all associated metadata.
Permanently relocate items to the digital refuse bin (with explicit user affirmation).
Toggling of message read/unread status.
Direct invocation of message viewing within a web browser interface.

✍️ Preliminary Draft Handling

Generation of unsent correspondence records for later finalization.
Indexing and display of all currently stored draft items.
Modification and updating of existing draft content.

🔖 Categorization & Tagging System

Cataloging and listing of all existing organizational tags.
Provision for creating bespoke classification labels.
Assignment or revocation of tags to specific electronic messages.
Facade for renaming established organizational tags.
Decommissioning of unused or obsolete tags.
Targeted retrieval of messages based on assigned category.

📂 Directory Structuring (Label Mapping)

Establishment of new organizational partitions (mapped internally as Gmail labels).
Migration of correspondence between these defined partitions.
Manifest of all presently configured directory structures.

🔎 Sophisticated Querying & Rule Definition

Execution of complex searches utilizing Gmail's proprietary advanced query language.
Provision for creating, maintaining, and eliminating automated message sorting rules.
Granular filtering based on originator, destination, subject line, content body, and ancillary data.
Customization of search result sets via adaptable parameters.

🗄️ Storage Management (Archival)

Execution of archival action (removing items from the primary inbox view without deletion).
Bulk archiving operation for numerous messages matching a predefined search pattern.
Inventory listing of all currently archived electronic documents.
Reinstatement of archived items back into the active inbox view.

🚀 Initialization Guide

Prerequisites

Execution environment requiring Python version 3.8 or newer.
A provisioned Google Cloud Platform project where the Gmail API has been formally activated.
Necessary OAuth 2.0 authorization credentials.

Deployment Steps

bash

Obtain the source code repository

git clone https://github.com/theposch/gmail-mcp.git cd gmail-mcp

Establish an isolated execution environment

python -m venv .venv source .venv/bin/activate # Windows users: .venv\Scripts\activate

Install the package in editable mode

pip install -e .

Google Cloud Credentialing Procedure

Initiate a new Google Cloud Project instance.
Activate the necessary Gmail API service endpoint.
Configure the OAuth consent portal:
Designate user type as "External".
Register your primary email address as a designated test user.
Incorporate the requisite scope: https://www.googleapis.com/auth/gmail/modify.
Generate the OAuth 2.0 access artifacts:
Select the application type as "Desktop application".
Securely download the resulting JSON credentials artifact.

Configuration Mapping

Safely store your authentication materials and designate their location upon server invocation:

bash

Suggested structure for credential storage

mkdir -p ~/.gmail-mcp

Transfer the downloaded client secret file

Example: move ~/Downloads/client_secret_*.json to the designated location

mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

🔧 Operational Context

Integration with Claude Desktop Environment

Incorporate the subsequent configuration block into your Claude Desktop settings file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "gmail": { "command": "uv", "args": [ "--directory", "/absolute/path/to/gmail-mcp", "run", "gmail", "--creds-file-path", "/absolute/path/to/credentials.json", "--token-path", "/absolute/path/to/tokens.json" ] } } }

Debugging via MCP Inspector Tool

For rigorous validation and diagnostic tracing, utilize the MCP Inspector utility:

bash npx @modelcontextprotocol/inspector uv run /path/to/gmail-mcp/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json

🔐 Security Protocols

CRITICAL: Ensure credential and token files are NEVER committed to any version control repository.
Maintain credentials within a protected directory with restricted access permissions.
The server employs mandatory user consent prompts before executing high-impact operations.
Periodically audit the Google Cloud Console for anomalous activity.
Prioritize the utilization of system environment variables for handling sensitive file paths.

🛠️ System Blueprint

This structure employs a unified, monolithic design encompassing all necessary interactions with Google's API client libraries for mail functions. Key architectural elements include:

OAuth2 authorization handler with automated token renewal capability.
Robust exception handling and comprehensive operational logging.
Clearly delineated tool definitions featuring precise input constraint schemas.
Optimized routines for parsing and formatting email payloads.

📚 Illustrative Interaction Queries

Execute these commands via Claude following the establishment of the GMAYL-CTL-PRO server connection:

"Display all messages currently marked as unread."
"Query for correspondence originating from example@domain.com that contains file attachments."
"Establish a new hierarchical tag named 'High-Priority Tasks'."
"Formulate an outgoing message addressed to john@example.com regarding the forthcoming assembly."
"Systematically move all correspondence from newsletter@example.com to the archive."
"Define an automated rule to assign the 'Team' label to incoming communications from organizational peers."

🤝 Community Contribution Guidelines

We actively encourage submissions! Feel free to propose enhancements via a Pull Request.

Fork the primary repository.
Initiate a dedicated feature branch (e.g., git checkout -b feature/enhanced-search).
Commit intended modifications (git commit -m 'Introduce feature X enhancement').
Push the branch upstream (git push origin feature/enhanced-search).
Submit a formal Pull Request.