Google Mail Interface for Model Context Protocol (MCP)

This MCP server establishes connectivity with the Gmail platform to enable sending, purging, fetching, drafting, and replying to electronic messages.

Crucial Note: This utility grants an MCP client the capability to access, delete, and transmit mail items. Nevertheless, prior to executing any such function, the system mandates explicit user confirmation.

https://github.com/user-attachments/assets/5794cd16-00d2-45a2-884a-8ba0c3a90c90

Functional Modules

Operations (Tools)

• dispatch-electronic-mail
• Transmits a message to a specified electronic mail recipient address
• Parameters:
  • recipient_id (text): The intended addressee's email address
  • subject (text): The title of the electronic communication
  • message (text): The core content of the correspondence

• Result: Confirmation status and a unique message identifier

• move-to-trash

• Relocates a specific electronic message to the designated trash receptacle
• Parameters:
  • email_id (text): The system-assigned identifier for the message

• Result: A confirmation message upon successful completion

• designate-as-reviewed

• Updates the status of a message to 'read'
• Parameters:
  • email_id (text): The system-assigned identifier for the message

• Result: A confirmation message upon successful completion

• fetch-unread-communications

• Retrieves a collection of electronic messages that have not yet been reviewed

• Result: A list of message objects, each containing its unique ID

• access-message-content

• Fetches the full content of a specified electronic message
• Parameters:
  • email_id (text): The system-assigned identifier for the message

• Result: A structured data object containing message metadata, and automatically sets the message status to 'read'

• launch-message-view

• Initiates the viewing of the specified electronic message within the default web browser
• Parameters:
  • email_id (text): The system-assigned identifier for the message
• Result: A success notification and activation of the default web browser for the message URL

Configuration Procedures

Google Mail API Credentials Establishment

1. Generate a new Google Cloud venture
2. Activate the Gmail API service
3. Configure the OAuth consent interface
   • Select the "external" designation. Publication will be intentionally omitted.
   • Enlist your personal electronic mail address as an authorized "Test user".
4. Incorporate the OAuth authorization scope: https://www.googleapis.com/auth/gmail/modify
5. Generate an OAuth Client Identification specifying the application type as "Desktop App"
6. Download the JSON artifact containing your client's authentication keys
7. Rename the downloaded key file appropriately and store it securely on your local apparatus. Document its precise location.
   • The full, unqualified path to this file must be supplied as the argument to the --creds-file-path option when initiating the server execution.

Authorization Handshake

Upon launching the server process, an authorization sequence will commence, utilizing your system's default web browser. Token credentials will subsequently be persisted (and later reloaded) to the file path specified by the --token-path parameter.

For instance, one might employ a hidden directory within the user's home structure, substituting [your-home-folder]:

Parameter	Illustrative Value
--creds-file-path	/[your-home-folder]/.google/client_creds.json
--token-path	/[your-home-folder]/.google/app_tokens.json

Integration with Desktop Client

Utilization of uv is suggested for package management.

To embed this server functionality within the Claude Desktop application operating as the MCP Client, augment your application's server configuration file with the subsequent block. By default, this configuration resides at ~/Library/Application\ Support/Claude/claude_desktop_config.json.

{ "mcpServers": { "gdrive": { "command": "uv", "args": [ "--directory", "[absolute-path-to-git-repo]", "run", "gmail", "--creds-file-path", "[absolute-path-to-credentials-file]", "--token-path", "[absolute-path-to-access-tokens-file]" ] } } }

The following configuration values are mandatory specifications: | Parameter | Illustrative Value | |-----------------|--------------------------------------------------| | --directory | The absolute location of the gmail repository housing the server code | | --creds-file-path | The absolute location of the credentials file generated during the Gmail API Setup phase. | | --token-path | The absolute location designated for saving and retrieving the application's access and refresh tokens. |

Diagnostics Using MCP Inspector

To verify server functionality, employ the MCP Inspector. Execute the following command from within the repository structure, ensuring parameter arguments are correctly substituted.

bash npx @modelcontextprotocol/inspector uv run [absolute-path-to-git-repo]/src/gmail/server.py --creds-file-path [absolute-path-to-credentials-file] --token-path [absolute-path-to-access-tokens-file]