# Gmail MCP Server
An MCP (Model Context Protocol) server that lets an AI assistant:
- Read your unread Gmail messages via the Gmail API
- Create properly threaded **draft replies** in Gmail
Built for the Anthropic programme foundation project as an end-to-end example.
---
## Features
### `get_unread_emails(maxResults: int = 10)`
Fetches unread emails from your inbox and returns a JSON structure:
```json
{
"emails": [
{
"id": "string",
"threadId": "string",
"from": "string",
"subject": "string",
"snippet": "string",
"internalDate": "string"
}
]
}
```
Fields:
- `id` – Gmail message ID
- `threadId` – Gmail thread ID (used when replying)
- `from` – sender
- `subject` – email subject
- `snippet` – short preview of the message
- `internalDate` – message timestamp (ms since epoch, as string)
### `create_draft_reply(threadId: str, replyBody: str)`
Creates a **draft reply** in the specified Gmail thread.
Returns a JSON structure:
```json
{
"draftId": "string | null",
"threadId": "string",
"to": "string",
"subject": "string"
}
```
- Correctly threads the reply using `In-Reply-To` and `References` headers.
- Leaves the draft in your Gmail Drafts folder for manual review / sending.
OAuth tokens are stored locally in `token.json` and refreshed automatically.
---
## Architecture / Tech Stack
- **Language:** Python 3
- **MCP server:** [`mcp` Python SDK (FastMCP)](https://pypi.org/project/mcp/)
- **Gmail API client:** `google-api-python-client`, `google-auth-oauthlib`
- **Client:** Claude Desktop using MCP over stdio
---
## Prerequisites
- Python 3.10+ installed
- Claude Desktop installed
- A Google account with access to Gmail
- A Google Cloud project with the Gmail API enabled
---
## Setup
1. **Clone the repository and create a virtual environment**
```bash
git clone <your-repo-url> gmail-mcp-server
cd gmail-mcp-server
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
2. **Create a Google Cloud project & enable Gmail API**
- Go to the Google Cloud Console.
- Create (or select) a project.
- Enable **Gmail API** for that project.
- Configure the OAuth consent screen (External / Testing is fine for personal use).
3. **Create OAuth credentials**
- In **APIs & Services → Credentials**, create an **OAuth client ID**.
- Application type: **Desktop app**.
- Download the JSON file and save it in the project root as:
```text
credentials.json
```
4. **First-time Gmail authentication (optional sanity check)**
The project includes a small script to verify Gmail is configured correctly:
```bash
source .venv/bin/activate
python debug_gmail.py
```
This will:
- Open a browser window asking you to sign in and approve Gmail scopes.
- Save a local `token.json` file for future runs.
- Print the IDs of your unread messages.
5. **Ignore local secrets and environment-specific files**
Make sure your `.gitignore` (in this repo) includes at least:
```gitignore
.venv/
__pycache__/
credentials.json
token.json
*.log
```
These files must **never** be committed to GitHub.
---
## Claude Desktop Configuration
Claude Desktop uses `claude_desktop_config.json` to know how to launch MCP servers.
On macOS this file is usually at:
```text
~/Library/Application Support/Claude/claude_desktop_config.json
```
Add (or merge) the following configuration:
```json
{
"mcpServers": {
"gmail-mcp-server": {
"command": "/Users/<you>/Code/gmail-mcp-server/.venv/bin/python",
"args": [
"/Users/<you>/Code/gmail-mcp-server/server.py"
],
"env": {
"GMAIL_CREDENTIALS_PATH": "/Users/<you>/Code/gmail-mcp-server/credentials.json"
}
}
}
}
```
Replace `/Users/<you>/Code/gmail-mcp-server` with the actual path to this project on your machine.
After editing the file, **quit and restart Claude Desktop** so it picks up the new MCP server.
---
## Usage in Claude
Once Claude Desktop is restarted, open a new chat and try:
### List and summarise unread emails
> “Use the `gmail-mcp-server` tools to call `get_unread_emails` with `maxResults` 5, then summarise the emails.”
Claude will:
- Call the `get_unread_emails` tool.
- Receive the JSON list of unread emails.
- Summarise them in natural language.
### Inspect raw JSON (for debugging / demo)
> “Call `get_unread_emails` with `maxResults` 3 and show me the raw JSON output.”
### Create a draft reply
1. First fetch unread emails and inspect the JSON to find a `threadId`.
2. Then:
> “Use the `gmail-mcp-server` tools to call `create_draft_reply` with this `threadId`: `<PASTE_THREAD_ID>` and a reply body that politely confirms I received their email and proposes a call next week. Tell me what `draftId` was created.”
3. Open Gmail → **Drafts** to see the newly created reply in the correct thread.
---
## Screenshots (for project submission)
Suggested screenshots to include in your submission / repo:
- Claude calling `get_unread_emails` and showing the JSON result.
- Claude summarising the unread emails.
- Claude calling `create_draft_reply` and reporting the created `draftId`.
- Gmail UI showing the draft reply in the correct thread.
Place them in a `screenshots/` folder and reference them in your application as needed.
---
## Security Notes
- This server is intended for **local, personal use** as a learning/demo project.
- `credentials.json` and `token.json` are sensitive and must remain local.
- Scopes are limited to:
- `gmail.readonly` – reading messages
- `gmail.compose` – creating drafts
- The server does **not** send credentials or email content to any third-party service other than Gmail and the local Claude Desktop client.
