Gmail Integration for Claude via MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop App (or any other app that supports MCP) to interact with Gmail, providing capabilities for reading, searching, and sending emails through a standardized interface.

Overview

This server bridges Claude AI with Gmail API, allowing Claude to:
- Send emails and replies
- Search and retrieve emails with advanced filters
- Read email content and attachments
- Work with Gmail categories and labels

By implementing the Model Context Protocol, it gives Claude the ability to perform authenticated Gmail operations while maintaining security and privacy.

Installation

Prerequisites

• Node.js 16 or later
• npm

Setup Steps

1. Create a Google Cloud Project and enable the Gmail API:
2. Go to Google Cloud Console
3. Create a new project
4. Enable the Gmail API
5. Create OAuth credentials (Desktop application)
6. Download the credentials JSON file as gcp-oauth.keys.json
7. Clone and Install:
   shell git clone https://github.com/cristip73/MCP-email-server.git cd MCP-email-server npm install
8. Build the Server:
   shell npm run build
9. Authenticate with Gmail:
   shell npm run auth
   This will open a browser window to authenticate with your Google account.
10. Make Package available to Claude:
    shell npm link

Usage with Claude

Claude Desktop

Add the MCP server to Claude Desktop:

Go into Claude Desktop settings then go into Developer Mode then choose Edit Config and edit the JSON file.

Example of a local config file for Claude Desktop

{
  "mcpServers": {
    "email-server": {
      "command": "node",
      "args": ["/path/to/email-server/build/index.js"],
      "env": {
          "TIME_ZONE": "GMT+2",
          "DEFAULT_ATTACHMENTS_FOLDER": "/Users/username/CLAUDE/Attachments"
      }     
    }
  }
}

IMPORTANT: Set the DEFAULT_ATTACHMENTS_FOLDER to a valid path on your system.

IMPORTANT: Set the TIME_ZONE to your local timezone in GMT format. Eg: GMT+2, GMT-5, etc. Otherwise the date and time of the emails will be off, it is set to GMT+0 by default by Gmail.

For Claude Code Editor, you can add the server by running the following command:

claude mcp add email-server -- /path/to/email-server/build/index.js

Project Structure

src/
├── index.ts                 # Entry point and server initialization
├── server.ts                # MCP server implementation
├── client-wrapper.ts        # Gmail API client wrapper with multi-account support
├── tool-handler.ts          # Tool registration and request routing
├── prompt-handler.ts        # Prompt management and template system
├── version.ts               # Version information
├── utils.ts                 # Shared utilities for dates, emails, etc.
├── timezone-utils.ts        # Timezone handling and configuration
└── tools/                   # Tool implementations by domain
    ├── email-read-tools.ts  # Tools for reading emails
    ├── email-send-tools.ts  # Tools for sending, replying and forwarding emails
    ├── email-search-tools.ts # Tools for searching and filtering emails
    ├── email-label-tools.ts # Tools for managing labels and message states
    ├── email-attachment-tools.ts # Tools for listing and saving attachments
    ├── email-draft-tools.ts # Tools for managing email drafts
    └── timezone-tool.ts     # Tool for verifying timezone configuration

Configuration

The server supports the following configuration:
- TIME_ZONE: Timezone configuration in format like 'GMT+2' or 'GMT-5' (default: 'GMT+0')
- DEFAULT_ATTACHMENTS_FOLDER: Path to the directory where email attachments can be saved (e.g., '/Users/username/CLAUDE/attachments')

Features

Email Operations

• Send Email: Send new emails with support for CC, BCC, and attachments
• Reply: Reply to existing emails while maintaining thread context
• Reply All: Reply to all recipients in a thread while filtering out your own addresses
• Forward: Forward emails to other recipients with original headers and formatting
• Read Email: Retrieve and display email content, headers, and attachments
• Search Emails: Search emails using Gmail's query syntax with enhanced features

Draft Management

• Create Drafts: Save email drafts for later editing or sending
• List Drafts: View all saved drafts with pagination support
• Update Drafts: Edit existing drafts with full content modification
• Send Drafts: Convert saved drafts to sent emails
• Delete Drafts: Remove drafts that are no longer needed

Advanced Functionality

• Pagination: Navigate through large result sets with pageToken support
• Gmail Categories: Filter by Gmail's categories (Primary, Social, Promotions, etc.)
• Time Filtering: Search by predefined time periods (today, yesterday, last 24h)
• Unread Status: Automatic handling of unread email filtering
• HTML Content: Process and display both HTML and plain text email content
• Thread Context: Maintain email threading for proper conversation context
• Multi-Account Support: Automatic handling of multiple sending addresses and aliases
• Smart Reply Addressing: Selection of correct sending address based on original recipient
• UTF-8 Encoding: Proper encoding of international characters in subject and body content
• Secure Attachment Handling: Restricted attachment saving to designated folder with path validation

Label Management

• Custom Labels: Create, update, and delete custom labels
• Label Visibility: Control visibility of labels in message list and label list
• Label Colors: Configure text and background colors for visual organization
• Message States: Mark messages as read/unread, archive/unarchive messages
• Trash Management: Move messages to trash

Time Zone Support

• Display and Query Emails: Display and query emails in the user's local time zone
• Time Zone Verification: Check the configured time zone and see current time adjustments
• Configurable Offset: Support for custom GMT offsets (GMT+2, GMT-5, etc.)
• Consistent Formatting: All timestamps displayed with the configured timezone
• Date Calculations: Search filters like "today" and "yesterday" properly adjusted for timezone

Attachment Management

• List Attachments: View all attachments in an email with full metadata (name, size, type)
• Save Attachments: Securely save attachments to the configured DEFAULT_ATTACHMENTS_FOLDER
• Path Security: Validation and normalization to prevent path traversal attacks
• File Integrity: Verification of saved files with size validation and error reporting
• Automatic Selection: Intelligent handling when no specific attachment ID is provided
• Multiple Attachments: Support for emails with multiple attachments
• Folder Creation: Automatic creation of necessary directories when saving attachments
• Error Handling: Comprehensive error handling for failed attachment operations

Available Tools

Send Email

send_email
Send a new email message.

Parameters:
- to: Array of recipient email addresses (required)
- subject: Email subject (required)
- body: Email body content (required)
- cc: Array of CC recipients
- bcc: Array of BCC recipients
- inReplyTo: Message ID to reply to
- threadId: Thread ID to add the message to

Reply All Email

reply_all_email
Reply to an email and include all original recipients (TO and CC).

Parameters:
- messageId: ID of the message to reply to (required)
- body: Email body content (required)
- additionalRecipients: Additional recipients to include in the reply
- excludeRecipients: Recipients to exclude from the reply
- from: Specific send-as email address to use as sender (optional)

Forward Email

forward_email
Forward an email to other recipients.

Parameters:
- messageId: ID of the message to forward (required)
- to: List of recipients to forward the email to (required)
- additionalContent: Additional content to add before the forwarded message
- cc: List of CC recipients
- from: Specific send-as email address to use as sender (optional)

List Send-As Accounts

list_send_as_accounts
List all accounts and email addresses that can be used for sending emails.

Parameters: None

Get Recent Emails

get_recent_emails
Get recent emails with support for time filters, categories, and read status.

Parameters:
- hours: Number of hours to look back
- maxResults: Maximum number of results to return (default: 25)
- query: Additional Gmail search query
- pageToken: Token for the next page of results
- category: Filter by Gmail category (primary, social, promotions, updates, forums)
- timeFilter: Predefined time filter (today, yesterday, last24h)
- autoFetchAll: Automatically fetch all results (up to 100) without requiring pagination

Read Email

read_email
Read a specific email by ID and extract its content.

Parameters:
- messageId: ID of the email message to retrieve (required)

Search Emails

search_emails
Search for emails using Gmail query syntax with support for categories and time filters.

Parameters:
- query: Gmail search query (required)
- maxResults: Maximum number of results to return (default: 25)
- pageToken: Token for the next page of results
- category: Filter by Gmail category (primary, social, promotions, updates, forums)
- timeFilter: Predefined time filter (today, yesterday, last24h)
- autoFetchAll: Automatically fetch all results (up to 100) without requiring pagination

Label Management Tools

List Labels

list_labels
List all labels in the user's mailbox.

Parameters: None

Get Label

get_label
Get details about a specific label.

Parameters:
- labelId: ID of the label to retrieve (required)

Create Label

create_label
Create a new label in the user's mailbox.

Parameters:
- name: Name of the label to create (required)
- messageListVisibility: Controls the label's visibility in the message list (show or hide)
- labelListVisibility: Controls the label's visibility in the label list (labelShow, labelShowIfUnread, or labelHide)
- textColor: Text color in hex format (e.g., #000000)
- backgroundColor: Background color in hex format (e.g., #ffffff)

Update Label

update_label
Update an existing label.

Parameters:
- labelId: ID of the label to update (required)
- name: New name for the label
- messageListVisibility: Controls the label's visibility in the message list (show or hide)
- labelListVisibility: Controls the label's visibility in the label list (labelShow, labelShowIfUnread, or labelHide)
- textColor: Text color in hex format (e.g., #000000)
- backgroundColor: Background color in hex format (e.g., #ffffff)

Delete Label

delete_label
Delete a label from the user's mailbox.

Parameters:
- labelId: ID of the label to delete (required)

Modify Labels

modify_labels
Add or remove labels from a message.

Parameters:
- messageId: ID of the message to modify (required)
- addLabelIds: Array of label IDs to add to the message
- removeLabelIds: Array of label IDs to remove from the message

Message Management Tools

Mark as Read

mark_as_read
Mark a message as read.

Parameters:
- messageId: ID of the message to mark as read (required)

Mark as Unread

mark_as_unread
Mark a message as unread.

Parameters:
- messageId: ID of the message to mark as unread (required)

Archive Message

archive_message
Archive a message (remove from inbox).

Parameters:
- messageId: ID of the message to archive (required)

Unarchive Message

unarchive_message
Move a message back to inbox.

Parameters:
- messageId: ID of the message to move to inbox (required)

Trash Message

trash_message
Move a message to trash.

Parameters:
- messageId: ID of the message to move to trash (required)

Draft Management Tools

Create Draft

create_draft
Create a new draft email without sending it.

Parameters:
- to: Array of recipient email addresses (required)
- subject: Email subject (required)
- body: Email body content (required)
- cc: Array of CC recipients
- bcc: Array of BCC recipients
- from: Specific send-as email address to use as sender

Get Draft

get_draft
Retrieve the contents of a specific draft.

Parameters:
- draftId: ID of the draft to retrieve (required)

List Drafts

list_drafts
List all drafts in the email account.

Parameters:
- maxResults: Maximum number of drafts to return (default: 20)
- pageToken: Token for the next page of results
- query: Search filter for drafts

Update Draft

update_draft
Update the content of an existing draft.

Parameters:
- draftId: ID of the draft to update (required)
- to: New list of recipient email addresses (required)
- subject: New email subject (required)
- body: New email body content (required)
- cc: New list of CC recipients
- bcc: New list of BCC recipients
- from: New specific send-as email address to use as sender

Delete Draft

delete_draft
Permanently delete a draft.

Parameters:
- draftId: ID of the draft to delete (required)

Send Draft

send_draft
Send an existing draft.

Parameters:
- draftId: ID of the draft to send (required)

Time Zone Tool

Get Timezone Info

get_timezone_info
Display information about the configured timezone in the system.

Parameters: None

Returns:
- Configured timezone (from the TIME_ZONE variable)
- Calculated offset in hours
- Current date and time adjusted to the timezone
- Current date and time in UTC for comparison

Attachment Management Tools

List Attachments

list_attachments
List all attachments in an email.

Parameters:
- messageId: ID of the message for which to list attachments (required)

Returns:
- List of all attachments with their details (name, type, size)
- Count of attachments in the email

Save Attachment

save_attachment
Save an attachment from an email to the configured DEFAULT_ATTACHMENTS_FOLDER.

Parameters:
- messageId: ID of the message containing the attachment (required)
- attachmentId: ID of the attachment (optional if the message has only one attachment)
- targetPath: Filename or relative path where the attachment will be saved (will be saved inside the DEFAULT_ATTACHMENTS_FOLDER)

Example Prompts

• "Send an email to [email protected] with subject 'Meeting Tomorrow'"
• "Get my emails from the last 24 hours"
• "Search for emails from [email protected]"
• "Find unread emails in my Primary category from yesterday"
• "Show me promotional emails containing 'discount' received today"
• "Create a new label called 'Project X' with blue background"
• "Show all my Gmail labels"
• "Mark this email as unread"
• "Archive all emails from this newsletter"
• "Move this email to my 'Important' label"
• "Create a draft to the team about the upcoming meeting"
• "Show me all my saved drafts"
• "Update my draft to include new information"
• "Send the draft I created earlier"
• "Delete the draft that I no longer need"
• "What's my current timezone configuration?"
• "Save the attachment from this email to my documents folder"
• "Forward this report to the management team"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.