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 docs 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 (Setup Guide)
Anthropic API key (Get one here)
Claude Desktop installed

Installation

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

Set up Google OAuth 2.0:

Follow the detailed OAuth Setup Guide to:
- Create a Google Cloud Project
- Enable Gmail API
- Configure OAuth consent screen
- Download credentials.json
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.

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-..."
      }
    }
  }
}

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 Usage Examples Guide and Style Guide Feature Guide.

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

Google OAuth 2.0 Setup Guide - Step-by-step OAuth configuration with screenshot placeholders
Usage Examples - Real-world usage examples and workflows with Claude Desktop
Troubleshooting Guide - 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 Troubleshooting Guide.

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