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

# 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:

{
  "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:

   NOTION_API_KEY=secret_abc123...
   NOTION_STYLE_GUIDE_PAGE_ID=abc123def456
   

4. Rebuild and restart:

   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>