# 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](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](docs/oauth-setup.md))
- Anthropic API key ([Get one here](https://console.anthropic.com))
- Claude Desktop installed
### Installation
1. **Clone and install dependencies:**
```bash
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 [OAuth Setup Guide](docs/oauth-setup.md) to:
- Create a Google Cloud Project
- Enable Gmail API
- Configure OAuth consent screen
- Download `credentials.json`
3. **Authenticate with Gmail:**
```bash
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`
```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 [Usage Examples Guide](docs/usage-examples.md) and [Style Guide Feature Guide](docs/style-guide-feature.md).
## 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](docs/oauth-setup.md) - Step-by-step OAuth configuration with screenshot placeholders
- [Usage Examples](docs/usage-examples.md) - Real-world usage examples and workflows with Claude Desktop
- [Troubleshooting Guide](docs/troubleshooting.md) - 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](https://myaccount.google.com/permissions)
## Development
Run the server manually for testing:
```bash
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](docs/troubleshooting.md).
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
