📌Overview

Purpose: The Gmail Server for Model Context Protocol (MCP) is designed to facilitate the integration of email functionalities within applications, allowing operations such as sending, removing, reading, drafting, and responding to emails.

Overview: This MCP server seamlessly connects with Gmail, enabling clients to manage emails effectively. Users are prompted for confirmation before actions like reading or sending emails are performed, ensuring control over operations.

Key Features:

• send-email: Sends an email to a specified recipient, taking in the recipient's address, subject, and message content; returns the status of the action and a message ID.

• trash-email: Moves a specified email to trash by using its auto-generated ID; confirms the action with a success message.

• mark-email-as-read: Marks a specific email as read, enhancing user organization; returns a confirmation of the action.

• get-unread-emails: Retrieves a list of unread emails including their IDs, helping users manage their inbox efficiently.

• read-email: Fetches the content of a given email, marks it as read, and returns its metadata for user reference.

• open-email: Opens a specified email in the default browser, providing a quick way for users to view email details; confirms successful action with a message.

---

Gmail Server for Model Context Protocol (MCP)

This MCP server integrates with Gmail to enable sending, removing, reading, drafting, and responding to emails.

Note: This server enables an MCP client to read, remove, and send emails. However, the client prompts the user before conducting such activities.

Components

Tools

• send-email

  • Sends email to email address recipient
  • Input:
    • recipient_id (string): Email address of addressee
    • subject (string): Email subject
    • message (string): Email content
  • Returns status and message_id

• trash-email

  • Moves email to trash
  • Input:
    • email_id (string): Auto-generated ID of email
  • Returns success message

• mark-email-as-read

  • Marks email as read
  • Input:
    • email_id (string): Auto-generated ID of email
  • Returns success message

• get-unread-emails

  • Retrieves unread emails
  • Returns list of emails including email ID

• read-email

  • Retrieves given email content
  • Input:
    • email_id (string): Auto-generated ID of email
  • Returns dictionary of email metadata and marks email as read

• open-email

  • Open email in browser
  • Input:
    • email_id (string): Auto-generated ID of email
  • Returns success message and opens given email in default browser

Setup

Gmail API Setup

1. Create a new Google Cloud project: https://console.cloud.google.com/projectcreate
2. Enable the Gmail API: https://console.cloud.google.com/workspace-api/products
3. Configure an OAuth consent screen: https://console.cloud.google.com/apis/credentials/consent
   • Select "external" (do not publish the app)
   • Add your personal email address as a "Test user"
4. Add OAuth scope https://www.googleapis.com/auth/gmail/modify
5. Create an OAuth Client ID for application type "Desktop App": https://console.cloud.google.com/apis/credentials/oauthclient
6. Download the JSON file of your client's OAuth keys
7. Rename and save the key file in a secure location on your machine. The absolute path to this file will be used as the --creds-file-path parameter when starting the server.

Authentication

When the server is started, an authentication flow will launch in your system browser.
Token credentials will be saved and retrieved from the file path passed to the --token-path parameter.

Example paths (using a dot directory in your home folder):

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

Usage with Desktop App

Using uv is recommended: https://docs.astral.sh/uv/

To integrate this server with Claude Desktop as the MCP Client, add the following to your app's server configuration (default location: ~/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]"
      ]
    }
  }
}

Required parameters:

Parameter	Description
--directory	Absolute path to gmail directory containing server
--creds-file-path	Absolute path to credentials file created in Gmail API Setup
--token-path	Absolute path to store and retrieve access and refresh tokens

Troubleshooting with MCP Inspector

To test the server, use MCP Inspector: https://modelcontextprotocol.io/docs/tools/inspector

From the git repo, run the following command with appropriate paths:

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]