Email MCP Server

A remote MCP (Model Context Protocol) server that connects Claude to Microsoft 365 Outlook and Google Gmail via their respective APIs. Deployed on Vercel with Claude Connector OAuth - Anthropic handles all authentication.

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Claude    │────►│   Anthropic  │────►│  Microsoft/     │
│   Client    │     │   (OAuth)    │     │  Google OAuth   │
└─────────────┘     └──────────────┘     └─────────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  Email MCP   │  ◄── Bearer token on every request
                    │   (Vercel)   │
                    └──────────────┘

Key points:

• Users connect via Claude Settings → Connectors
• Anthropic handles the OAuth flow (authorization, token refresh, secure storage)
• MCP server receives Authorization: Bearer <token> with each request
• Server is stateless - no token storage, no auth tools, no database

Features

Microsoft 365 (Outlook)

• Search emails by date, sender, subject, attachments, read status
• Invoice detection with multi-language keywords (English + Hebrew)
• Read full email content
• Download attachments with PDF text extraction
• Folder management (list, create, find)
• Move emails between folders (single or batch)
• Create drafts

Google (Gmail)

• Search with Gmail query syntax
• Invoice detection with keyword matching
• Read emails and full conversation threads
• Download attachments
• Label management (list, create, delete, modify)
• Create drafts

Shared Features

• Session-based short IDs - Uses 1, 2, 3... instead of long API IDs
• Invoice keyword detection - invoice, receipt, billing, payment, חשבונית, חשבוניות
• Provider extraction - Extracts vendor names from email domains
• PDF text extraction - Extracts text from PDF attachments
• Image vision - Returns images for Claude to analyze

Session-Based Short IDs

The MCP uses short IDs instead of long Graph/Gmail IDs:

Graph ID: AAMkADQ5NWE3...longstring...AAAA=
                    ↓
Short ID: 1

Benefits:

• Reduces token usage
• Easier to reference in follow-up commands
• Works with messages, folders, attachments, and labels

Note: Short IDs are stored in-memory and reset when the session ends.

Setup

Prerequisites

1. Vercel account - vercel.com
2. Azure AD App Registration (for Microsoft 365)
3. Google Cloud OAuth credentials (for Gmail)

Azure AD Setup

1. Go to Azure Portal → Azure Active Directory → App registrations
2. Create new registration
3. Add API permissions: Mail.ReadWrite, User.Read, offline_access
4. Add redirect URI: https://claude.ai/api/mcp/auth_callback
5. Copy the Application (client) ID and Directory (tenant) ID

Google Cloud Setup

1. Go to Google Cloud Console
2. Enable the Gmail API
3. Configure OAuth consent screen
4. Create OAuth 2.0 credentials
5. Add redirect URI: https://claude.ai/api/mcp/auth_callback
6. Add scopes:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.modify
   • https://www.googleapis.com/auth/gmail.labels

Deployment

1. Clone the repository
2. Link to Vercel: vercel link
3. Set environment variables in Vercel Dashboard:
   • AZURE_CLIENT_ID - Azure app client ID
   • AZURE_TENANT_ID - Azure tenant ID
4. Deploy: vercel deploy --prod

Note: Client secrets are NOT stored in the MCP server - Anthropic handles OAuth securely.

Connecting to Claude

After deployment:

1. Go to Claude.ai → Settings → Connectors
2. Add your Vercel deployment URL
3. Authorize with Microsoft and/or Google when prompted
4. Start using email tools in Claude

Available Tools

Microsoft 365 (Outlook)

Tool	Description
m365_search_emails	Search emails with flexible filtering
m365_search_invoice_emails	Find invoice emails with keyword detection
m365_read_email	Read full email content
m365_list_attachments	List attachments of an email
m365_download_attachment	Download a specific attachment
m365_download_attachment_by_name	Download attachment by filename
m365_download_all_invoices	Batch download invoice attachments
m365_list_folders	List mail folders
m365_find_folder	Find folder by path or name
m365_get_folder_tree	Get complete folder hierarchy
m365_create_folder	Create a new mail folder
m365_move_email	Move a single email
m365_move_emails	Move multiple emails
m365_list_providers	List vendors from invoice emails
m365_create_draft	Create a draft (does not send)

Google (Gmail)

Tool	Description
google_search_emails	Search with Gmail query syntax
google_search_invoice_emails	Find invoice emails
google_read_email	Read full message content
google_read_thread	Read entire conversation thread
google_list_attachments	List attachments of a message
google_download_attachment	Download attachment by filename
google_list_labels	List all Gmail labels
google_get_label	Get label details
google_create_label	Create a new label
google_delete_label	Delete a label
google_modify_labels	Add/remove labels from messages
google_list_providers	List vendors from invoice emails
google_create_draft	Create a draft (does not send)

Example Workflows

Organize Invoices (Microsoft 365)

1. m365_search_invoice_emails(year: 2024)       → Find invoices
2. m365_create_folder(displayName: "Invoices")  → Create folder
3. m365_move_emails(messageIds: [...], destinationFolderName: "Invoices")

Search and Label (Gmail)

1. google_search_emails(query: "from:amazon.com has:attachment")
2. google_search_invoice_emails(year: 2024)
3. google_modify_labels(messageIds: [...], addLabelIds: ["Label_123"])

Read Conversation

1. google_search_emails(sender: "support@company.com")
2. google_read_thread(threadId: ...)

Tool Parameters

General Email Search

Parameter	Type	Description
startDate	string	Start date (ISO format)
endDate	string	End date (ISO format)
year	number	Year to search
month	number	Month (1-12)
sender	string	Sender email address
subject	string	Subject contains
hasAttachments	boolean	Filter by attachments
isUnread	boolean	Filter by read status
folderId/labelId	string	Search within folder/label
maxResults	number	Maximum results
format	string	"full", "summary", "minimal", "ids"

Invoice Search

Parameter	Type	Description
year	number	Required. Year to search
month	number	Month (1-12)
sender	string	Sender email address
keywords	string[]	Custom search keywords
maxResults	number	Maximum results

Move Emails (M365)

Parameter	Type	Description
messageId/messageIds	string/string[]	Email ID(s) to move
destinationFolderId	string	Folder ID or well-known name
destinationFolderName	string	Folder display name
createIfNotExists	boolean	Create folder if missing

Well-known folders: inbox, drafts, sentitems, deleteditems, archive, junkemail, outbox

Development

Local Testing

npm run dev       # Start local Next.js server
# Connect MCP Inspector to http://localhost:3000/api/mcp

Build

npm run build     # Build for production

Invoice Detection

The server searches for emails containing these keywords:

• English: invoice, receipt, bill, payment, billing, statement, order confirmation, tax invoice
• Hebrew: חשבונית, קבלה, תשלום, חשבונית מס, אישור הזמנה

Attachment Filtering

Only downloads invoice-relevant files:

• PDF files
• Images (PNG, JPG, JPEG, TIFF)

Skips:

• Calendar files (.ics)
• Contact files (.vcf)
• HTML files
• Signature images (files containing "signature", "logo", "banner")

License

MIT