Email Agent

An MCP server that turns Claude Desktop into your email assistant. It connects to Gmail, reads your inbox, classifies emails, drafts replies in your voice, and sends them with your approval.

What it does

• Fetches your unread emails and sorts them into groups: spam, notifications, simple replies, drafts, and escalations
• Auto-trashes spam and auto-archives notifications from senders you configure
• Drafts replies in your writing style using a customizable knowledge base
• Sends approved replies and archives handled emails
• All actions require your approval before anything is sent

Prerequisites

• Python 3.10+ (check with python3 --version)
• A Gmail account
• Claude Desktop (download here)

Setup

1. Set up Google Cloud credentials

This is the longest step, but you only do it once.

1. Go to Google Cloud Console
2. Click Select a project at the top, then New Project. Name it anything (e.g. "Email Agent") and click Create
3. Make sure your new project is selected, then:
   • Go to APIs & Services > Library in the left sidebar
   • Search for Gmail API and click Enable
4. Set up the consent screen:
   • Go to APIs & Services > OAuth consent screen
   • Choose External and click Create
   • Fill in "App name" (e.g. "Email Agent") and your email for support/developer contact
   • Click through the Scopes page (no changes needed)
   • On the Test users page, click Add users and add your Gmail address
   • Click Save and Continue
5. Create your credentials:
   • Go to APIs & Services > Credentials
   • Click Create Credentials > OAuth client ID
   • Choose Desktop app as the application type
   • Click Create, then Download JSON
   • Save the file somewhere you can find it (your Downloads folder is fine)

2. Run the setup wizard

cd email-agent
python3 setup_wizard.py

The wizard will:

• Install Python dependencies
• Ask you to paste the path to the JSON file you downloaded
• Open your browser to sign in with Google
• Ask for your name, sign-off style, and spam/notification senders
• Print the config snippet for Claude Desktop

3. Add to Claude Desktop

Copy the config snippet the wizard prints and add it to your Claude Desktop config file:

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

The snippet looks like this (the wizard fills in the correct paths for you):

{
  "mcpServers": {
    "email-agent": {
      "command": "/path/to/python3",
      "args": ["/path/to/mcp_server.py"]
    }
  }
}

If you already have other MCP servers, just add the "email-agent" entry inside your existing "mcpServers" object.

4. Use it

Restart Claude Desktop, then say:

• "Process my emails" -- full workflow: fetch, classify, draft replies, send
• "Check my inbox" -- just see what's unread
• "Send an email to ..." -- compose and send a new email

Configuration

Edit ~/.email-agent/config.yaml to customize:

Setting	What it does
auto_trash_senders	Emails from these senders/domains go straight to trash
auto_archive_senders	Emails from these senders/domains get archived silently
cc_rules	Auto-CC someone when certain keywords appear in an email
escalation_keywords	Emails with these keywords are shown to you instead of auto-drafted
category_keywords	Custom categories for organizing draft replies

For auto_trash_senders and auto_archive_senders, you can use full email addresses (noreply@linkedin.com) or just domains (linkedin.com).

Knowledge Base

Put .md files in ~/.email-agent/knowledge_base/ to teach the agent your style and context:

File	Purpose
tone.md	How you write (included by default)
corrections.md	Learned corrections from edited drafts (auto-populated)
faq.md	Common questions and your preferred answers
templates.md	Reply templates by category

Troubleshooting

"Run setup_wizard.py first" -- You need to run the setup wizard before the MCP server will work. It creates the credentials and config files.

OAuth error / "Access blocked" -- Make sure you added your Gmail address as a test user in the Google Cloud Console (step 1.4 above).

"Python 3.10+ required" -- Your system Python is too old. Install a newer version via python.org, Homebrew (brew install python), or conda.

MCP server not showing up in Claude Desktop -- Make sure the command path in your config points to the Python that has the dependencies installed. The setup wizard prints the correct path for you.

Token expired -- Restart the MCP server (restart Claude Desktop). If that doesn't work, delete ~/.email-agent/token.json and run the wizard again.

Requirements

• Python 3.10+
• A Gmail account
• Claude Desktop