UBOS Asset Marketplace: Gmail IMAP MCP Server

In the rapidly evolving landscape of AI-driven solutions, the ability for AI agents to seamlessly interact with real-world data and tools is paramount. UBOS is at the forefront of this revolution, providing a full-stack AI Agent Development Platform designed to empower businesses across all departments. Our platform facilitates the orchestration of AI Agents, connects them with enterprise data, and enables the construction of custom AI Agents using your preferred LLM model and Multi-Agent Systems.

Within the UBOS ecosystem, the Gmail IMAP MCP Server stands out as a critical asset. This server acts as a bridge, enabling AI assistants to directly interface with Gmail accounts using the Model Context Protocol (MCP). By leveraging IMAP, it provides a robust and standardized method for AI agents to read, search, manage, and even send emails, opening up a wealth of automation possibilities.

Use Cases: Transforming Email Interactions with AI

The Gmail IMAP MCP Server unlocks a plethora of use cases, transforming how businesses and individuals interact with email.

• Automated Customer Support: Imagine an AI agent that can automatically triage incoming customer support emails, identify urgent issues, and even draft initial responses. The MCP server empowers this by providing the AI with the ability to read and understand the content of incoming emails, extract relevant information, and then use that information to formulate appropriate actions.
• Intelligent Email Filtering and Organization: Tired of sifting through endless emails? An AI-powered system, driven by the MCP server, can intelligently categorize and label emails based on content, sender, and other criteria. It can automatically move important emails to specific folders, flag urgent messages, and even unsubscribe from unwanted newsletters, ensuring a clean and organized inbox.
• Meeting Scheduling and Reminders: Forget the back-and-forth of scheduling meetings. An AI assistant can use the MCP server to access your calendar, analyze email threads for proposed meeting times, and automatically schedule meetings, sending out reminders to all participants.
• Lead Generation and Qualification: For sales and marketing teams, the MCP server can be used to analyze incoming emails for potential leads. It can identify individuals expressing interest in your products or services, automatically qualify them based on predefined criteria, and then route them to the appropriate sales representative.
• Personalized Email Marketing: AI agents can leverage the MCP server to personalize email marketing campaigns. By analyzing customer data and past interactions, the AI can tailor email content to individual preferences, increasing engagement and conversion rates.
• Contact Form Automation: Efficiently handle website contact form submissions by automatically extracting key information such as sender details and the message content. This allows for quicker and more personalized responses.
• Enhanced AI Agent Capabilities: Specifically designed to work well with tools like Claude, the MCP server handles common issues like backticks in JSON, ensuring smooth integration and reliable performance.

Key Features: Powering Intelligent Email Management

The Gmail IMAP MCP Server boasts a rich set of features designed to empower AI agents with comprehensive email management capabilities.

• OAuth2 Authentication: Ensures secure access to Gmail accounts using the industry-standard OAuth2 protocol, protecting user credentials and data.
• Comprehensive Email Retrieval: Allows AI agents to read emails from Gmail accounts with advanced search capabilities, including filtering by dates, labels, keywords, and more. This granular control ensures that the AI can quickly find the information it needs.
• Advanced Search Functionality:
  • Gmail-Style Query Syntax: Supports Gmail-style queries like from:example@gmail.com is:unread has:attachment for intuitive and powerful search capabilities.
  • Special Characters Support: Enables querying labels with special characters (e.g., label:$$$$$).
  • Date Range Filtering: Facilitates searching emails by date ranges using after_date and before_date parameters.
  • Combined Filtering: Allows mixing and matching search criteria for precise email filtering.
  • Additional Search Parameters: Filters by read/unread status, attachments, and more.
• Email Sending with Attachments: Enables AI agents to send emails with attachments, allowing for automated communication and document sharing.
• Label Management: Provides functionality to create, delete, and list labels, allowing AI agents to organize and categorize emails effectively.
• Email Organization: Allows AI agents to move emails between labels, mark emails as read/unread, and download attachments, enabling efficient inbox management.
• Multiple Account Support: Supports multiple Gmail accounts, allowing AI agents to manage email for multiple users or departments.
• MCP Integration: Seamlessly integrates with AI assistants through the Model Context Protocol, providing a standardized interface for email interactions.
• Contact Form Email Processing:
  • Automated Detection: Identifies emails sent from website contact forms.
  • True Sender Extraction: Extracts the actual sender from Reply-To headers or embedded From lines.
  • Website Source Identification: Shows which website the contact form came from.
  • Clean Message Extraction: Extracts just the message content, removing form metadata.
  • Improved Display Format: Shows contact form emails in a clear, structured format.
• Backtick JSON Handling: Added support for handling Claude’s tendency to use backticks in JSON:
  • Automatic Conversion: Converts backtick-formatted JSON (name) to proper JSON (“name”)
  • Error Handling: Provides helpful error messages about JSON format issues
  • Seamless Integration: Works automatically, no special handling needed

Deep Dive into Key Tools and Functions for Claude Desktop

For users leveraging Claude Desktop as their AI assistant, the Gmail IMAP MCP Server provides specific tools and best practices for optimal email handling.

• Reply Functions (CRITICAL):
  • reply-to-message: For responding to newly arrived emails without prior communication.
  • reply-to-thread: For continuing existing conversations with existing back-and-forth communication.
  • IMPORTANT: Always use the appropriate reply function to maintain email threading.
• Email Content Retrieval:
  • get-email: Essential for retrieving full email content, including body, headers, and true sender information for contact forms, before responding.

Best Practices for Claude

1. Always Get Full Email Content: Use get-email before responding to see the complete message, including true sender information.
2. Use Proper Reply Functions: Never use send-email when responding to existing emails. Employ reply-to-message or reply-to-thread instead.
3. Handle Contact Forms Correctly: Extract true sender information from contact form submissions using get-email.
4. Mark Emails as Read: Mark emails as read after handling to avoid duplicate responses.
5. Thread Management: Use reply-to-thread to continue existing conversations and maintain proper email threading.

Recommended Workflow for Claude

1. Search for unread emails using get-unread-emails.
2. For each unread email, use get-email to retrieve the full content.
3. Determine if this is a new conversation or a continuation of an existing thread.
4. Use the appropriate reply function (reply-to-message or reply-to-thread).
5. Mark the email as read using mark-as-read.

Architecture and Implementation Highlights

The Gmail IMAP MCP Server is built with security, persistence, and compatibility in mind.

• Credential Storage: OAuth2 credentials are securely stored in the user’s home directory (~/.gmail_imap_mcp_credentials/) for enhanced security and persistence.
• IMAP Implementation: Utilizes Python’s imaplib2 library for secure and efficient IMAP operations with Gmail, including OAuth2 authentication and intelligent Gmail query parsing.
• Email ID Format: Employs a unique email ID format (email://message/{account}_{mailbox}_{id}) to ensure consistent identification of emails across different accounts and mailboxes.

Getting Started with the Gmail IMAP MCP Server

Integrating the Gmail IMAP MCP Server into your UBOS platform is straightforward. Follow these steps to unleash the power of AI-driven email management:

1. Prerequisites: Ensure you have Python 3.12 or higher, a Google Cloud Project with the Gmail API enabled, and OAuth 2.0 Client ID credentials.
2. Installation: Clone the repository, create a virtual environment, and install the package using pip install -e ..
3. Google Cloud Project Setup: Create or select a Google Cloud Project, enable the Gmail API, and create OAuth 2.0 credentials. Download the client configuration file and save it as client_secret.json in the credentials directory (~/.gmail_imap_mcp_credentials/).
4. Configuration: Start the server using the command gmail-imap-mcp.
5. Authentication: Use the authenticate-gmail tool to authenticate your Gmail account and follow the OAuth2 authentication flow in your browser.
6. Integration with AI Assistants: Configure your AI assistant (e.g., Claude Desktop, Windsurf IDE) to connect to the Gmail IMAP MCP Server using the provided configuration snippets.

The UBOS Asset Marketplace’s Gmail IMAP MCP Server empowers your AI agents to communicate like humans, creating seamless and productive workflows.