Gmail IMAP MCP Server

A Model Context Protocol (MCP) server for Gmail integration using IMAP. This server allows AI assistants to interact with Gmail accounts, providing functionality to read, search, and manage emails.

Features

OAuth2 authentication with Gmail
Read emails from Gmail accounts
Search emails with advanced query options
View unread emails
Send emails with attachments
Manage labels (create, delete, list)
Move emails between labels
Download attachments
Mark emails as read/unread
Support for multiple Gmail accounts
Integration with AI assistants through MCP

Prerequisites

Before running the Gmail IMAP MCP server, ensure you have the following:

Python 3.12 or higher
Google Cloud Project with Gmail API enabled
OAuth 2.0 Client ID credentials

Installation

Install from source

Clone the repository:

git clone https://github.com/yourusername/gmail-imap-mcp.git
cd gmail-imap-mcp

Create and activate a virtual environment:

python -m venv .venv
# On Windows
.venv\Scripts\activate
# On Unix/MacOS
source .venv/bin/activate

Install the package:
```
pip install -e .
```

Setup Google Cloud Project

Go to the Google Cloud Console
Create a new project or select an existing one
Enable the Gmail API for your project:
- Navigate to "APIs & Services" > "Library"
- Search for "Gmail API" and enable it
Create OAuth 2.0 credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose "Desktop app" as application type
- Download the client configuration file

Save the downloaded file as client_secret.json in the credentials directory:

mkdir -p ~/.gmail_imap_mcp_credentials
# Move the downloaded file to ~/.gmail_imap_mcp_credentials/client_secret.json

Architecture and Implementation Details

Credential Storage

The Gmail IMAP MCP server stores OAuth2 credentials in the user's home directory at ~/.gmail_imap_mcp_credentials/. This approach offers several advantages:

Security: Credentials are stored in a user-specific location rather than in the application directory
Persistence: Credentials persist across different sessions and application restarts
Compatibility: Avoids permission issues on read-only file systems

The credentials directory contains:

client_secret.json: Your OAuth client credentials from Google Cloud Console
Token files for each authenticated Gmail account (format: token_{email_address}.json)

IMAP Implementation

The server uses Python's imaplib2 library for IMAP operations with Gmail. Key implementation details include:

Connection: Secure connection to Gmail's IMAP server (imap.gmail.com) on port 993
Authentication: OAuth2 authentication using XOAUTH2 mechanism
Email Retrieval: Emails are retrieved using RFC822 format and parsed with Python's email module
Label Management: Gmail labels are managed through IMAP mailbox operations

Email ID Format

Email IDs in the system follow this format:

email://message/{account}_{mailbox}_{id}

Where:

{account}: The Gmail account address
{mailbox}: The mailbox/label containing the email
{id}: The unique IMAP ID of the email

This format allows the system to uniquely identify emails across different accounts and mailboxes.

Usage

Starting the Server

Run the Gmail IMAP MCP server:

gmail-imap-mcp

Authenticating Gmail Accounts

Use the authenticate-gmail tool with your email address
Follow the OAuth2 authentication flow in your browser
Once authenticated, the server will store your credentials for future use

Available Tools and Examples

The Gmail IMAP MCP server provides a comprehensive set of tools for interacting with Gmail accounts. Below is a detailed list of all available tools along with examples of how to use them.

Authentication

1. authenticate-gmail

Authenticate a Gmail account to use with the MCP server.

Parameters:

email: Email address to authenticate

Example:

{
  "name": "authenticate-gmail",
  "arguments": {
    "email": "[email protected]"
  }
}

Email Retrieval and Search

2. search-emails

Search for emails in a Gmail account using various search criteria.

Parameters:

account: Email account to search in
mailbox: Mailbox to search in (default: INBOX)
query: Search query
limit: Maximum number of emails to return (default: 10)

Example - Search for emails from a specific sender:

{
  "name": "search-emails",
  "arguments": {
    "account": "[email protected]",
    "mailbox": "INBOX",
    "query": "from:[email protected]",
    "limit": 5
  }
}

Example - Search for emails with a specific subject:

{
  "name": "search-emails",
  "arguments": {
    "account": "[email protected]",
    "query": "subject:\"Meeting Invitation\""
  }
}

Example - Search for emails with specific text in the body:

{
  "name": "search-emails",
  "arguments": {
    "account": "[email protected]",
    "query": "TEXT \"project update\""
  }
}

3. get-unread-emails

Get unread emails from a Gmail account.

Parameters:

account: Email account to get emails from
mailbox: Mailbox to get emails from (default: INBOX)
limit: Maximum number of emails to return (default: 10)

Example:

{
  "name": "get-unread-emails",
  "arguments": {
    "account": "[email protected]",
    "limit": 20
  }
}

Email Composition and Sending

4. send-email

Send an email from a Gmail account with optional attachments and HTML content.

Parameters:

account: Email account to send from
to: Recipient email address(es), comma-separated for multiple
subject: Email subject
body: Plain text email body
cc: Carbon copy recipients (optional)
bcc: Blind carbon copy recipients (optional)
html_body: HTML version of the email body (optional)
attachments: List of attachment objects (optional)
- Each attachment object requires:
  - path: Path to the file
  - filename: Custom filename (optional)
  - content_type: MIME type (optional)

Example - Simple email:

{
  "name": "send-email",
  "arguments": {
    "account": "[email protected]",
    "to": "[email protected]",
    "subject": "Hello from Gmail MCP",
    "body": "This is a test email sent via the Gmail IMAP MCP server."
  }
}

Example - Email with CC, BCC, and HTML content:

{
  "name": "send-email",
  "arguments": {
    "account": "[email protected]",
    "to": "[email protected]",
    "subject": "Meeting Agenda",
    "body": "Please find the agenda for our upcoming meeting.",
    "cc": "[email protected]",
    "bcc": "[email protected]",
    "html_body": "<h1>Meeting Agenda</h1><p>Please find the agenda for our <b>upcoming meeting</b>.</p>"
  }
}

Example - Email with attachment:

{
  "name": "send-email",
  "arguments": {
    "account": "[email protected]",
    "to": "[email protected]",
    "subject": "Document Attached",
    "body": "Please find the attached document.",
    "attachments": [
      {
        "path": "/path/to/document.pdf",
        "filename": "important_document.pdf",
        "content_type": "application/pdf"
      }
    ]
  }
}

Label Management

5. create-label

Create a new label/mailbox in a Gmail account.

Parameters:

account: Email account to create label in
label_name: Name of the label to create

Example:

{
  "name": "create-label",
  "arguments": {
    "account": "[email protected]",
    "label_name": "ProjectX"
  }
}

6. delete-label

Delete a label/mailbox from a Gmail account.

Parameters:

account: Email account to delete label from
label_name: Name of the label to delete

Example:

{
  "name": "delete-label",
  "arguments": {
    "account": "[email protected]",
    "label_name": "OldProject"
  }
}

7. list-labels

List all labels/mailboxes in a Gmail account.

Parameters:

account: Email account to list labels from

Example:

{
  "name": "list-labels",
  "arguments": {
    "account": "[email protected]"
  }
}

Email Organization

8. move-email

Move an email from one label/mailbox to another.

Parameters:

account: Email account
email_id: Email ID to move (format: email://message/{account}_{mailbox}_{id})
source_mailbox: Source mailbox
target_mailbox: Target mailbox

Example:

{
  "name": "move-email",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345",
    "source_mailbox": "INBOX",
    "target_mailbox": "ProjectX"
  }
}

Attachment Handling

9. download-attachment

Download an attachment from an email.

Parameters:

account: Email account
email_id: Email ID (format: email://message/{account}_{mailbox}_{id})
attachment_index: Index of the attachment to download (0-based)
mailbox: Mailbox containing the email (default: INBOX)
download_dir: Directory to save the attachment to (default: "downloads")

Example:

{
  "name": "download-attachment",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345",
    "attachment_index": 0,
    "download_dir": "my_attachments"
  }
}

Email Status Management

10. mark-as-read

Mark an email as read.

Parameters:

account: Email account
email_id: Email ID (format: email://message/{account}_{mailbox}_{id})
mailbox: Mailbox containing the email (default: INBOX)

Example:

{
  "name": "mark-as-read",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345"
  }
}

11. mark-as-unread

Mark an email as unread.

Parameters:

account: Email account
email_id: Email ID (format: email://message/{account}_{mailbox}_{id})
mailbox: Mailbox containing the email (default: INBOX)

Example:

{
  "name": "mark-as-unread",
  "arguments": {
    "account": "[email protected]",
    "email_id": "email://message/[email protected]_INBOX_12345"
  }
}

Available Prompts

The server provides the following prompts for AI assistants to use:

1. summarize-emails

Creates a summary of recent emails.

Parameters:

account: Email account to summarize
mailbox: Mailbox to summarize (default: INBOX)
count: Number of emails to summarize (default: 5)

Example:

{
  "name": "summarize-emails",
  "arguments": {
    "account": "[email protected]",
    "mailbox": "INBOX",
    "count": 10
  }
}

Integration with AI Assistants

The Gmail IMAP MCP server can be integrated with AI assistants that support the Model Context Protocol (MCP). Here's a typical workflow:

Authentication: The AI assistant uses the authenticate-gmail tool to authenticate the user's Gmail account.
Email Management: The assistant can retrieve, search, and manage emails using the various tools provided by the server.
Email Composition: The assistant can help draft and send emails based on user instructions.
Email Organization: The assistant can help organize emails by creating labels, moving emails between labels, and marking emails as read/unread.
Email Summarization: The assistant can summarize emails using the summarize-emails prompt.

Connecting with AI Assistants

Claude Desktop

To connect the Gmail IMAP MCP server with Claude Desktop:

Start the Gmail IMAP MCP server:
```
python -m gmail_imap_mcp.server
```
Open Claude Desktop and navigate to Settings (gear icon)
Scroll down to the "Advanced" section and click on "Edit MCP Configuration"

Add the Gmail IMAP MCP server configuration:

{
  "servers": [
    {
      "name": "Gmail IMAP",
      "url": "http://localhost:8080",
      "tools": [
        "list-emails",
        "get-email",
        "search-emails",
        "send-email",
        "list-mailboxes",
        "create-label",
        "move-email",
        "mark-as-read",
        "download-attachment"
      ]
    }
  ]
}

Click "Save" and restart Claude Desktop
You can now ask Claude to interact with your Gmail account, for example:
- "Show me my unread emails"
- "Send an email to [recipient] about [subject]"
- "Create a new label called 'Important'"
- "Move the email from [sender] to the 'Important' label"

Windsurf IDE

To connect the Gmail IMAP MCP server with Windsurf IDE:

Start the Gmail IMAP MCP server:
```
python -m gmail_imap_mcp.server
```
Open Windsurf IDE and navigate to Settings
Find the "AI Flow" or "MCP Configuration" section

Add the Gmail IMAP MCP server configuration:

{
  "servers": [
    {
      "name": "Gmail IMAP",
      "url": "http://localhost:8080",
      "tools": [
        "list-emails",
        "get-email",
        "search-emails",
        "send-email",
        "list-mailboxes",
        "create-label",
        "move-email",
        "mark-as-read",
        "download-attachment"
      ]
    }
  ]
}

Save the settings and restart Windsurf if necessary
You can now ask Cascade (Windsurf's AI assistant) to interact with your Gmail account using the same commands as with Claude Desktop

Common Use Cases

1. Email Triage

Assistant: I'll help you triage your unread emails.
User: Yes, please check my unread emails.
Assistant: [Uses get-unread-emails tool]
Assistant: You have 5 unread emails. The most urgent appears to be from your boss about the quarterly report due tomorrow.
User: Mark that as read and I'll look at it right away.
Assistant: [Uses mark-as-read tool]

2. Email Search and Organization

Assistant: Would you like me to find specific emails for you?
User: Yes, find all emails from [email protected] about the project budget.
Assistant: [Uses search-emails tool with query "from:[email protected] project budget"]
Assistant: I found 3 emails from John about the project budget. Would you like me to create a label for these?
User: Yes, create a "Budget" label and move them there.
Assistant: [Uses create-label tool followed by move-email tool for each email]

3. Email Composition

Assistant: Would you like me to draft an email for you?
User: Yes, write a follow-up email to the marketing team about our campaign results.
Assistant: [Drafts email content]
Assistant: Here's a draft. Would you like me to send it?
User: Yes, but add Sarah in CC.
Assistant: [Uses send-email tool with the drafted content and CC]

Gmail-Specific Considerations

Label Naming Conventions

Gmail has specific requirements for label names:

Label names are case-sensitive
Some special characters may not be allowed
System labels (like INBOX, Sent, Trash) cannot be created or deleted
Nested labels are represented with a forward slash (e.g., "Projects/ProjectX")

Email ID Format

The email ID format used by this MCP server is:

email://message/{account}_{mailbox}_{id}

When using tools that require an email ID (like mark-as-read or move-email), make sure to use the complete resource URI returned by email retrieval tools.

Security Considerations

The server stores OAuth2 credentials locally in the ~/.gmail_imap_mcp_credentials directory
Never share your client_secret.json or token files
The server only connects to Gmail's IMAP server using secure connections
Email attachments are downloaded to the downloads directory by default
Be cautious when using the server in shared environments to protect email data

Troubleshooting

Authentication Issues

Ensure your client_secret.json is correctly placed in the ~/.gmail_imap_mcp_credentials directory
Check that you've enabled the Gmail API in your Google Cloud Project
Try re-authenticating if your token has expired
If you see "Read-only file system" errors, ensure the credentials directory is writable

Connection Issues

Verify your internet connection
Ensure that your Google account doesn't have any security restrictions that might block IMAP access
Check if you need to enable "Less secure app access" in your Google account settings

Email Sending Issues

Verify that your Gmail account allows SMTP access
Check if you need to enable "Less secure app access" in your Google account settings
Ensure attachments are not too large (Gmail has a 25MB limit)

Label Management Issues

If creating labels fails, check if the label already exists (case-sensitive)
System labels cannot be created or deleted
Ensure label names follow Gmail's naming conventions

Email Movement Issues

If moving emails between labels fails, ensure both source and target labels exist
Check that the email ID format is correct
Verify that you have sufficient permissions to modify the email

Email ID Parsing Issues

If operations on email IDs fail, ensure you're using the complete resource URI
The system parses the last part of the URI as the actual email ID
Format should be: email://message/{account}_{mailbox}_{id}

License

MIT License

Support

For issues and feature requests, please open an issue on the GitHub repository.