Gmail Interface Module for Model Context Protocol (MCP)

This module functions as an MCP server, enabling client applications (like Claude Desktop) to interact with a personal Gmail repository.

Core Capabilities

• Access and display recent electronic correspondence from the connected mailbox.
• Execute complex searches against email data using standard Gmail query language.
• Ensure secure connectivity via delegated OAuth 2.0 authorization flow.

Deployment Sequence

Phase 1: Google Cloud Environment Configuration

1. Establish a new project within the Google Cloud Console (access via https://console.cloud.google.com/).
2. Activate the necessary Gmail Application Programming Interface (API).
3. Generate OAuth 2.0 Credentials:
   • Set the application type to 'Desktop Application'.
   • Save the resulting configuration file as credentials.json.

Phase 2: Software Installation

bash

Environment setup using Conda

conda create --name mcp-gmail python=3.12 conda activate mcp-gmail

Install the package from source directory

cd gmail-mcp-server pip install -e .

Phase 3: Configuration for Client Integration (e.g., Claude Desktop)

Modify your primary configuration file (claude_desktop_config.json) to include the server definition:

{ "mcpServers": { "gmail_interface": { "command": "/path/to/conda/envs/mcp-gmail/bin/python", "args": ["-m", "gmail_mcp_server.server"], "env": { "PYTHONPATH": "/path/to/gmail-mcp-server/src", "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json", "GMAIL_TOKEN_FILE": "/path/to/token.json" } } } }

Note: Adjust all /path/to/ placeholders to reflect the actual directory structure. The token file generation occurs automatically upon initial authorization.

Phase 4: Initial Execution and Authorization

The first attempt to access Gmail services through the client will trigger a browser redirection, asking the user to grant application permissions. Successful authorization results in token persistence in the designated token file.

Accessible Data Endpoints

• gmail://inbox/recent - Retrieves the ten chronologically newest messages.

Available Operational Tools

• execute_email_query
• Rationale: Facilitates the searching of stored messages within the Gmail repository.
• Parameters:
  • query_string (Mandatory): The search criteria, adhering strictly to Gmail's intrinsic search syntax.
  • result_limit (Optional): Specifies the maximum count of records to be returned (Defaults to 10).

Usage Example:

Retrieve correspondence from the 'sanrio' sender that arrived within the last 48 hours.

Security Posture

This service mandates OAuth2 authorization for interaction with the Gmail API: - Authorization prompt appears upon first invocation. - Authentication credentials (tokens) are stored locally, protected. - Access rights can be revoked anytime via the user's Google Account management interface. - Only read-only permissions concerning the mailbox are requested; no modification capabilities are sought.

Required Environment Configuration Variables

• GMAIL_CREDENTIALS_FILE: File path pointing to the Google OAuth client secret configuration.
• GMAIL_TOKEN_FILE: File path designated for persistent storage of the user's access token.

To initiate the server independently for diagnostic purposes: bash GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \ GMAIL_TOKEN_FILE="/path/to/token.json" \ python -m gmail_mcp_server.server

Development Notes

The server leverages the MCP structure to provide: - Structured access to message resources. - A dedicated utility function for parameterized message retrieval. - Robust handling of the secure token exchange process. - Automated renewal of expired access tokens.

Diagnostic Output

Operational details, including server startup validation, authentication handshake status, resource calls, tool invocations, and any encountered exceptions, are directed to standard error (stderr) streams for monitoring.