sgroi-l/email-mcp-server

Email MCP Server

An MCP (Model Context Protocol) server that brings email management capabilities to Claude Desktop. Fetch unread emails, generate AI-powered draft replies, and manage your Gmail inbox using natural language.

Check the for more detailed set up instructions and usage examples.

What It Does

This server integrates Gmail with Claude Desktop, allowing you to:

• Fetch unread emails from your Gmail inbox
• Generate contextual draft replies with customizable tone using Claude AI
• Save drafts directly to Gmail with proper email threading
• Send emails via Gmail API
• Interact with your inbox using natural language in Claude Desktop

Features

• OAuth 2.0 Authentication: Secure Google authentication (no app passwords needed)
• AI-Powered Replies: Generate smart email replies using Claude
• Style Guide Integration: Pull email style guides from Google Docs or any URL to ensure consistent messaging
• Email Threading: Maintains conversation threads when replying
• Flexible Tone Control: Choose professional, casual, or friendly tones for replies
• Direct Gmail Integration: Drafts appear in your Gmail Drafts folder

Quick Start

Prerequisites

• Python 3.8+
• Gmail account
• Google Cloud Project with Gmail API enabled ()
• Anthropic API key (Get one here)
• Claude Desktop installed

Installation

1. Clone and install dependencies:

   cd email-mcp-server
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

2. Set up Google OAuth 2.0:

   Follow the detailed to:

   • Create a Google Cloud Project
   • Enable Gmail API
   • Configure OAuth consent screen
   • Download credentials.json

3. Authenticate with Gmail:

   source venv/bin/activate
   python gmail_auth.py
   

   This opens your browser to authorize the app and saves a token.json file.

4. Configure Claude Desktop:

   Add to your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "email": {
         "command": "/absolute/path/to/email-mcp-server/venv/bin/python",
         "args": ["/absolute/path/to/email-mcp-server/email_server.py"],
         "env": {
           "ANTHROPIC_API_KEY": "sk-ant-api03-..."
         }
       }
     }
   }
   

5. Restart Claude Desktop

Usage

Once configured, interact with your emails in Claude Desktop using natural language:

• "Show me my unread emails"
• "Generate a professional reply to the first email"
• "Draft a friendly response mentioning the project is on track"
• "Generate a reply using my company style guide at https://docs.google.com/document/d/YOUR_DOC_ID/export?format=txt"
• "Save that reply as a draft in Gmail"

For more examples and workflows, see the and .

Available Tools

The server provides four MCP tools that Claude can use:

get_unread_emails

Fetches unread emails from Gmail. Optional parameter: max_emails (default: 10)

generate_draft_reply

Generates AI-powered email replies. Parameters: email_from, email_subject, email_body, email_date, optional tone, additional_context, and style_guide_url

Style Guide Support: Pass a style_guide_url parameter to fetch an external email style guide (e.g., from Google Docs). The AI will follow the style guide when generating replies. For Google Docs, use the export URL format:

https://docs.google.com/document/d/YOUR_DOC_ID/export?format=txt

Style guides are cached for 1 hour to improve performance.

save_draft

Saves draft emails to Gmail. Parameters: to, subject, body, optional in_reply_to for threading

send_email

Sends emails immediately. Parameters: to, subject, body

Documentation

• - Step-by-step OAuth configuration with screenshot placeholders
• - Real-world usage examples and workflows with Claude Desktop
• - Common issues and solutions

Security

• Never commit credentials.json or token.json (already in .gitignore)
• OAuth tokens are stored locally in token.json
• Refresh tokens enable automatic re-authentication
• Revoke access anytime at Google Account Permissions

Development

Run the server manually for testing:

cd email-mcp-server
source venv/bin/activate
python email_server.py

Troubleshooting

For common issues like OAuth errors, permission problems, or Claude Desktop integration issues, see the .

Quick fixes:

• OAuth issues: Make sure you're added as a test user in Google Cloud Console
• Permission errors: Delete token.json and re-run python gmail_auth.py
• MCP not working: Verify paths are absolute in Claude Desktop config and restart the app

License

MIT License