mcp-gmail

A toy demo of an MCP server that can write you some nifty draft emails

https://github.com/user-attachments/assets/2dcba8aa-81c5-4098-bccd-d07a6324be7c

Requirements

• uv
• claude desktop
• a google workspace setup with desktop application access for the Gmail API (steps Setup Your Environment through Authorize Credentials For a Desktop Application) with gmail.readonly and gmail.compose scopes

Example claude_desktop_config.json

{
  "mcpServers": {
    "email": {
      "command": "uv",
      "args": ["--directory", "/your/path/to/mcp-gmail", "run", "main.py"]
    },
  "preferences": {
    "quickEntryShortcut": "off"
  }
}

Getting started in Claude Desktop

• Clone the repo,
• Add the MCP server to your claude_desktop_config.json (see above)
• Quit and restart the application
• The MCP server should run via the stdio transport locally; you can check it's enabled in the 'connectors' section of the prompt (click the + icon)

What The Server Does

This repository implements a Gmail automation server using FastMCP and the Google Gmail API. The gmail.py file contains a Gmail class that handles authentication with the Gmail API and provides methods for interacting with Gmail, such as get_unread_messages to retrieve unread emails, get_thread to fetch an entire email thread, and create_draft to compose a draft reply within a specific thread. The models.py file defines Pydantic models for structuring Gmail message data, ensuring data integrity and type safety when interacting with the dynamic Gmail API responses. The main.py file sets up a FastMCP server, exposing the Gmail functionalities as callable tools: get_unread_emails, get_email_thread, and create_draft_reply. This allows external clients to interact with Gmail programmatically through a well-defined API, enabling automated email processing and drafting. The server is designed to run locally, authenticating users and performing actions on their behalf.

Notes

• I was using Claude Desktop, and my original plan was to use MCP Sampling, but Claude Desktop does not appear to support sampling; instead we just expose the tools needed to draft an email
• AuthN/AuthZ through MCP clients/servers feels somewhat complex; this just has the app deal with it when it spins up.
• The messages returned by the Gmail API are unread, but don't appear to have guaranteed ordering: the first message returned might not be the most recent message. This is likely to be undesired behaviour.