outlook_mcp

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

1. 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