Gmail Adapter for Model Context Protocol (MCP)

This MCP service establishes connectivity with Google Mail, empowering an MCP client to send, delete, retrieve, draft, and reply to messages.

Crucially, while this adapter permits the MCP client to access, purge, and transmit emails, it mandates that the end-user provide explicit authorization before executing any such transaction.

Link to Visual Aid

Functional Modules

Available Operations (Tools)

• transmit-mail
• Dispatches an electronic message to a specified recipient address.
• Parameters:
  • recipient_id (string): The electronic mail address of the intended receiver.
  • subject (string): The title or subject line of the communication.
  • message (string): The textual body content of the correspondence.

• Output: Operation status and a unique message identifier.

• relocate-to-trash

• Permanently shifts an email item to the designated deleted items folder.
• Parameters:
  • email_id (string): The internally assigned identifier corresponding to the email.

• Output: Confirmation of successful relocation.

• set-read-status

• Changes the flag on an email to indicate it has been reviewed.
• Parameters:
  • email_id (string): The system-generated unique identifier for the message.

• Output: A success notification.

• fetch-unread-inbox-items

• Retrieves a compilation of messages that have not yet been opened.

• Output: A structured list containing all unread emails, including their respective identifiers.

• retrieve-message-body

• Fetches and displays the complete content of a specified email.
• Parameters:
  • email_id (string): The unique identifier of the message to be viewed.

• Output: A data structure detailing the email's metadata and automatically flags the item as read.

• launch-email-viewer

• Initiates the default web browser to display the content of a specific email.
• Parameters:
  • email_id (string): The unique identifier associated with the email item.
• Output: A success confirmation and invocation of the default web client for the specified email.

Initial Configuration

Google Mail API Setup Prerequisites

1. Establish a new Google Cloud resource container
2. Activate the Gmail Service Interface
3. Configure the OAuth consent interface
   • Designation must be "external". Note: The application will not be publicly released.
   • Add your own primary email address as a designated "Test user".
4. Authorize the scope: https://www.googleapis.com/auth/gmail/modify
5. Generate an OAuth Client Identifier for the "Desktop Application" type.
6. Download the configuration file (JSON format) containing your client's secret keys.
7. Rename the downloaded key file appropriately and store it securely on your local system. Record its absolute storage location.
   • This full path will be supplied to the --creds-file-path argument when launching the service.

Authorization Protocol

Upon service initiation, a web-based authorization sequence will commence in your default web browser. The resulting token credentials will be persisted (and later reloaded) at the file path specified by the --token-path argument.

Example storage locations, replacing [your-home-folder]:

Argument Name	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

Deployment via uv is suggested.

To link this service with the Claude Desktop application as the MCP Consumer, insert the subsequent configuration block into your application's server configuration file (default path usually ~/Library/Application\ Support/Claude/claude_desktop_config.json).

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

The following configuration fields are mandatory: | Parameter Identifier | Example Specification | |----------------------|------------------------------------------------------| | --directory | Absolute location of the repository containing the server script. | | --creds-file-path | Absolute path to the credential file generated during API Setup. | | --token-path | Absolute path designated for storing and retrieving active session tokens. |

Debugging via MCP Inspector

To validate the service's functionality, utilize the MCP Inspector utility. Execute the following command from the source repository directory, substituting the placeholder arguments as necessary:

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]