# Gmail MCP Server

An MCP (Model Context Protocol) server that allows AI assistants to read unread emails from a Gmail account.

## Features

- **OAuth 2.0 Authentication**: Secure access to Gmail with user consent
- **Read Unread Emails**: Fetch unread emails with sender, subject, snippet, and thread information
- **Create Draft Replies**: Compose draft responses to emails while maintaining thread continuity
- **Style Guide Integration**: Pull email writing guidelines from Notion to ensure consistent, professional communication

## Quick Start

```bash
# 1. Install dependencies
pnpm install

# 2. Build the server
pnpm build

# 3. Set up OAuth - follow the prompts (once)
pnpm setup:gmail

# 4. Get your MCP configuration (once)
./get-config.sh

# 5. (Optional) Set up Notion integration for style guides
# Add to .env.local:
# NOTION_API_KEY=your_notion_api_key
# NOTION_STYLE_GUIDE_PAGE_ID=your_page_id

# 6. Run the MCP server
pnpm start
```

Then add the configuration to Claude Desktop and restart the app!

## MCP Configuration

Run `./get-config.sh` to get your configuration, then add it to your Claude Desktop config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Configuration format:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/absolute/path/to/foundation-project-mcp/dist/emailServer.js"
      ]
    }
  }
}
```

## Available Tools

### `get_unread_emails`

Retrieves unread emails from the Gmail inbox.

**Parameters:**
- `maxResults` (optional): Maximum number of emails to retrieve (default: 10, max: 50)

**Example prompts:** "Show me my unread emails" • "What unread emails do I have?" • "Get my recent unread messages"

### `create_draft_reply`

Creates a draft reply to an email in a thread.

**Parameters:**
- `messageId` (required): The messageId of the original email
- `threadId` (required): The threadId of the original email
- `sender` (required): The sender of the original email
- `subject` (required): The subject of the original email
- `replyBody` (required): The draft reply content

### `get_style_guide`

Retrieves the email writing style guide from Notion (if configured).

**Parameters:** None

**Returns:** Email writing guidelines and best practices from your Notion page

## Example prompts

- "Show me my unread emails"
- "What unread emails do I have?"
- "Get my recent unread messages"
- "Get the email style guide and then draft a response to my latest unread email"
- "Create a draft reply to this email saying..."
- "Draft a response to the email from [sender]"
- "Draft a response to important unread emails following our style guide"

**Scroll down for screenshots of some of these prompts in action.**

## Notion Setup (Optional)

To enable the style guide feature:

1. **Create a Notion Integration:**
   - Go to https://www.notion.so/my-integrations
   - Click "New integration"
   - Give it a name (e.g., "Gmail MCP Server")
   - Copy the "Internal Integration Token"

2. **Create a Style Guide Page:**
   - Create a new page in Notion with your email writing guidelines
   - Click "Share" and invite your integration
   - Copy the page ID from the URL (the part after the page name and before the `?`)
     - Example: `https://notion.so/Email-Style-Guide-abc123def456` → Page ID is `abc123def456`

3. **Update `.env.local`:**
   ```bash
   NOTION_API_KEY=secret_abc123...
   NOTION_STYLE_GUIDE_PAGE_ID=abc123def456
   ```

4. **Rebuild and restart:**
   ```bash
   pnpm build
   # Restart Claude Desktop
   ```

## Security Notes

- Never commit `.env.local` (contains sensitive credentials)
- Uses `gmail.readonly` and `gmail.compose` OAuth scopes
- Access tokens auto-refresh when expired
- Email headers are sanitised to prevent injection attacks
- Notion integration token should be kept secure and never shared

## Troubleshooting

- **Invalid credentials / Token errors**: Re-run `pnpm setup:gmail`
- **No emails returned**: Check you have unread emails and Gmail API is enabled in Google Cloud Console

## Demo

<details>
<summary>"Show me my unread emails"</summary>

<img width="791" height="630" alt="Screenshot 2025-12-07 at 16 19 49" src="https://github.com/user-attachments/assets/f8d507f8-6582-41ab-8881-44e1cfcfa161" />
<img width="759" height="662" alt="Screenshot 2025-12-07 at 16 23 11" src="https://github.com/user-attachments/assets/c21d9e6b-9984-44c0-8575-16aec1fbff01" />
<img width="762" height="409" alt="Screenshot 2025-12-07 at 16 23 23" src="https://github.com/user-attachments/assets/138ede87-5358-4303-89e8-3e5325679771" />


</details>

<details>
<summary>"Draft replies to my unread emails"</summary>
  
<img width="763" height="620" alt="Screenshot 2025-12-07 at 16 34 49" src="https://github.com/user-attachments/assets/b8803487-de21-42c8-b89a-49167d50e0fc" />
<img width="765" height="570" alt="Screenshot 2025-12-07 at 16 35 03" src="https://github.com/user-attachments/assets/050c3bf7-a298-45f1-9978-94499c13a1e1" />
<img width="749" height="204" alt="Screenshot 2025-12-07 at 16 35 12" src="https://github.com/user-attachments/assets/19f2b496-99d3-413d-bec1-ea3068a961e9" />

</details>

<details>
<summary>"Did i receive any good newsletters today?"</summary>

<img width="775" height="764" alt="Screenshot 2025-12-07 at 16 38 46" src="https://github.com/user-attachments/assets/6e09662d-fd13-46a6-a380-acade13e5af3" />

</details>

<details>
<summary>Gmail and Notion screenshots</summary>

<img width="963" height="307" alt="Screenshot 2025-12-07 at 16 51 41" src="https://github.com/user-attachments/assets/3e9942a3-b8c8-4042-aff1-14688524bbe5" />
<img width="674" height="271" alt="Screenshot 2025-12-07 at 16 51 52" src="https://github.com/user-attachments/assets/8d25943f-ce1d-44d2-94de-810b17c51e80" />
<img width="927" height="461" alt="Screenshot 2025-12-07 at 16 52 20" src="https://github.com/user-attachments/assets/07309756-e950-4166-b0d1-26a6759b5754" />


</details>