# 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](https://developers.google.com/workspace/gmail/api/quickstart/python#set-up-environment) (steps **Setup Your Environment** through **Authorize Credentials For a Desktop Application**) with `gmail.readonly` and `gmail.compose` scopes
## Example `claude_desktop_config.json`
```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.
