AuraMail Nexus Gateway for Intelligent Desktop Integration

This Model Context Protocol (MCP) service acts as a bridge, empowering Claude Desktop to interact intelligently with your Gmail correspondence and Google Calendar entries, ensuring highly informed and personalized workflow management.

✨ Core Capabilities

• Holistic Message Assimilation: Derives comprehensive understanding from entire dialogue threads.
• Situational Response Generation: Formulates replies acutely aware of preceding communications.
• Automated Insight Flagging: Scans content to flag potential appointments, required actions, and necessary follow-up tasks.
• Agenda Synchronization: Converts identified time-based data within emails into concrete calendar bookings using natural language parsing.
• Deep Archive Querying: Executes complex, meaning-based searches across your complete message repository.
• Personalized Interaction Tuning: Refines output based on established communication dynamics with specific recipients.

🛠️ Deployment Instructions

Prerequisites Checklist

• Operational environment running Python version 3.10 or newer.
• Access credentials for the Google Cloud Platform, with the Gmail API and Calendar API services explicitly activated (optional, but recommended).
• Valid OAuth 2.0 credentials specifically for the aforementioned Google APIs (optional).
• A running instance of Claude Desktop configured to recognize and utilize MCP servers.

Installation Pathways

Method A: Automated Deployment via Smithery

Leverage the Smithery CLI for streamlined setup:

bash npx -y @smithery/cli install @bastienchabal/gmail-mcp --client claude

Method B: Manual Repository Setup

1. Obtain the source code repository: bash git clone https://github.com/bastienchabal/gmail-mcp.git cd gmail-mcp

2. Configure a dedicated virtual environment using the uv package manager: bash pip install uv uv venv source .venv/bin/activate # Substitute for Windows: .venv\Scripts\activate

3. Install all requisite project dependencies: bash uv pip install -e .

⚙️ System Configuration

Phase 1: Google Credential Authorization

1. Navigate to the Google Cloud Console.
2. Establish a new GCP project or select an existing project container.
3. Enable the necessary APIs:
   • Activate the Gmail API service endpoint
   • Activate the Calendar API service endpoint
4. Configure the OAuth Consent Screen:
   • Set the user type designation to "External".
   • Register your own email address as an authorized test user.
   • Ensure that the complete set of required Gmail and Calendar API scopes is included.
5. Generate and secure your OAuth 2.0 credentials:
   • Designate the application type as "Desktop app".
   • Download the resulting JSON credential file and securely extract the Client ID and Client Secret.

Phase 2: Integrating with Claude Desktop Configuration

1. Locate or generate the configuration file: claude_desktop_config.json within the designated application support directory (e.g., /Users/<username>/Library/Application Support/Claude).
2. Insert the following structural configuration block, replacing all bracketed placeholders with your actual security parameters:

{ "mcpServers": { "gmail-mcp": { "command": "//gmail-mcp/.venv/bin/mcp", "args": [ "run", "//gmail-mcp/gmail_mcp/main.py:mcp" ], "cwd": "//gmail-mcp", "env": { "PYTHONPATH": "//gmail-mcp", "CONFIG_FILE_PATH": "//gmail-mcp/config.yaml", "GOOGLE_CLIENT_ID": "", "GOOGLE_CLIENT_SECRET": "", "TOKEN_ENCRYPTION_KEY": "" } } } }

Configuration Notes: - Substitute <absolute-path> with the full, verified file system path to your gmail-mcp root directory. - Populate <your-client-id> and <your-client-secret> with the credentials generated in Step 5 of Phase 1. - Optional: Generate a robust encryption key using the command: python -c "import os; from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

This setup centralizes confidential access data within the Claude Desktop settings, reserving non-sensitive operational parameters for the local config.yaml file.

Phase 3: Activation within Claude Desktop

1. Launch the Claude Desktop application.
2. Initiate an interaction, for example: "Can you fetch the most recent correspondence I received?"
3. The system should automatically attempt connection to the MCP service and prompt for initial Gmail authorization (which generates the tokens.json file).

❓ Issue Resolution

Critical Note Regarding MCP Connectivity

If Claude Desktop fails to establish a connection (indicated by the absence of the tool icon below the input field), attempt the following steps: - Perform a full restart of the Claude Desktop client. - Explicitly instruct Claude: "Engage the AuraMail Nexus Gateway server." - Manually trigger the authentication flow using one of the dedicated debugging scripts provided.

Critical Note Regarding Authorization Failures

1. Authorization Diagnostics: Execute the test utility: python debug/auth_test.py for granular diagnostic output.
2. Token Location: Confirm the presence of the authentication token file in the repository's root directory.
3. Google Console Verification: Double-check that the precise redirect URI is registered correctly within your Google Cloud project.
4. Scope Confirmation: Ensure all prerequisite scopes have been explicitly added to the OAuth consent screen settings.
5. Scope Change Errors: If you encounter messages referencing scope modifications, verify that the openid scope is active.
6. Redirect Mismatch: If you receive redirect_uri_mismatch errors, input the exact URI displayed in the error message into the authorized redirect URIs section of the Google Cloud Console.
7. Port Conflict: If the authorization callback page fails to load or process, check if another background process is actively utilizing TCP port 8000.

Critical Note Regarding Calendar Integration Re-synchronization

Activating Calendar features after an initial Gmail-only setup requires re-authorization to secure Calendar API permissions. If you have existing tokens and are enabling Calendar functionality, you must force a re-authentication cycle by:

1. Erasing the existing token persistence file (tokens.json, potentially located in the project root or a specialized token directory like ~/Users/<username/>/gmail_mcp_tokens/tokens.json).
2. Relaunching the MCP service instance.
3. Proceeding through the standard initial authentication procedure once more.

🧭 Operational Guide

The AuraMail Nexus provides sophisticated tooling for command over your mail and scheduling:

Mail Handling Functions

• Inbox Summary: Retrieve high-level metrics, including message counts and previews of recent arrivals.
• Advanced Querying: Utilize Gmail's full spectrum of search operators for precise targeting.
• In-Depth Context Retrieval: Access individual messages complete with their full thread history and sender metadata.

Contextual Reply Facilitation

• Threadual Pre-Drafting: Analyze the entirety of an ongoing exchange prior to composing a reply.
• Relationship Modeling: Analyze historical correspondence patterns with the specific sender.
• Style Mimicry: Generate responses that align with your established tone for particular contacts.
• Entity Extraction: Automatically pinpoint critical elements like deadlines, appointments, and required actions.
• Cross-Reference Context: Integrate context from thematically related emails when formulating responses.

Calendar Coordination

• Appointment Generation: Create new schedule entries based on textual descriptions of time and location.
• Event Sensing: Proactively identify scheduled items embedded within message content.
• Schedule Oversight: Query, review, and manage forthcoming appointments.
• Intelligent Booking: Schedule necessary meetings using contextual information derived from the relevant email thread.

Illustrative Interaction Prompts

Examples of natural language commands Claude can execute: - "Provide a digest of my current inbox status." - "Search for all unread mail originating from the finance director concerning Q3 projections." - "Draft a follow-up to the latest message from Alex regarding the product launch timeline." - "Schedule the meeting referenced in Maria's email onto my calendar." - "What are the appointments listed on my calendar for the subsequent week?" - "Summarize the critical decision points within this email discussion before I respond." - "Compose a rebuttal to this message, ensuring it reflects my prior correspondence style with this client."

Accessible Contextual Resources

Claude can access the following data models provided by this MCP: - Message Context: Granular details of selected emails. - Thread Context: The complete chronological history of an email chain. - Sender Context: Historical communication metadata related to the correspondent. - Authorization State: Current authentication status with Google services. - Gmail Operational Status: A snapshot of the linked Gmail account health. - Service Metadata: Configuration details pertaining to the Nexus Gateway server itself.

Available Instructional Guides

Guides embedded within the service documentation: - Initial Setup Guide: Essential first steps for activation. - Authorization Troubleshooting Guide: Detailed steps for resolving credential issues. - Search Syntax Reference: Comprehensive list of advanced Gmail search operators. - Reply Generation Best Practices: Guidance on leveraging contextual drafting. - Diagnostic Protocols: Procedures for diagnosing common operational hurdles.

☑️ Safety Precaution: This MCP is configured such that Claude will invariably request explicit user consent before executing any action with significant external impact (e.g., dispatching mail or booking calendar entries).

⚠ Development Status

This component is currently under active development and should be treated as a Beta release.

📝 Licensing Information

This software is distributed under the permissive MIT License.

🤝 Acknowledgements

• This implementation utilizes the Model Context Protocol (MCP) framework, originally conceived by Anthropic.
• Access to core email and calendar functionalities is facilitated by Google's standardized API services.