gmail-mcp

xamde/gmail-mcp

3.2

If you are the rightful owner of gmail-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This document provides a comprehensive summary of a Java-based Gmail Model Context Protocol (MCP) server, designed to integrate AI agents with Gmail using the Java ecosystem.

Tools

  1. sendEmail

    Sends a new email with specified recipient, subject, and body.

  2. readEmail

    Fetches the full content of a single email by its ID.

  3. searchEmails

    Searches emails based on a query and returns a list of email summaries.

  4. trashEmail

    Moves an email to the trash.

  5. markAsRead

    Marks an email as read.

Project Plan: A Production-Grade Gmail MCP Server in Java

This document outlines the strategic rationale and a detailed, phased development plan for creating a robust, open-source Gmail MCP Server using the Java ecosystem. The primary technology stack will be the official MCP Java SDK accelerated by Spring AI and Spring Boot, establishing a benchmark for enterprise-grade AI tooling in Java.

Document Purpose: This document outlines the strategic rationale and a detailed, phased development plan for creating a robust, open-source Gmail MCP Server using the Java ecosystem. The primary technology stack will be the official MCP Java SDK accelerated by Spring AI and Spring Boot, establishing a benchmark for enterprise-grade AI tooling in Java. Target Audience: Development Team, Project Managers, and Architects.

1. Rationale & Strategic Vision ("The Why")

The Model Context Protocol (MCP) is rapidly becoming the industry standard for integrating AI agents with external tools, creating a new paradigm for automated workflows. Our research indicates a vibrant ecosystem of MCP servers for services like GitHub, Slack, and JIRA, primarily in Python and JavaScript. However, a significant gap exists in the enterprise Java ecosystem: there is no mature, open-source, and production-ready Gmail MCP server. This project directly addresses that gap. By building this server, we will unlock significant value:

  • Enable Enterprise Java AI: Provide a critical, missing piece of infrastructure for the vast number of enterprises that rely on Java and the Spring Framework. This allows them to build powerful, next-generation AI agents that can securely interact with a core business communication tool. Use cases range from AI-powered executive assistants that can summarize and triage inboxes to automated systems that process incoming customer support requests or financial invoices directly from Gmail.
  • Establish a Reference Architecture: Create a definitive, best-practice example of how to build high-quality, secure, and maintainable MCP servers using Spring AI. This architecture will demonstrate key enterprise patterns, including secure OAuth 2.0 token management, clean separation of concerns between authentication and tool logic, robust error handling, and comprehensive configuration management.
  • Promote the Java MCP Ecosystem: Contribute a high-value, reusable asset to the open-source community. This will not only provide immediate utility but also serve as a catalyst, encouraging further development and adoption of MCP within the Java world. We will actively promote this work through blog posts and community engagement to build momentum.

2. Running the Server

Locally

  1. Build the project: mvn clean install
  2. Run the application: java -jar target/gmail-mcp-server-1.0.0.jar

Docker

  1. Build the Docker image: docker build -t gmail-mcp-server .
  2. Run the Docker container: docker run -p 8080:8080 -v $(pwd)/credentials:/app/credentials -v $(pwd)/tokens:/app/tokens gmail-mcp-server

3. MCP Tool Reference

sendEmail

  • Description: Sends a new email.
  • Parameters:
    • to (String): The recipient's email address.
    • subject (String): The subject of the email.
    • body (String): The body of the email.
    • attachmentPaths (List): A list of local file paths to attach.
  • Example Return Value: "Email sent successfully"

readEmail

  • Description: Reads an email.
  • Parameters:
    • messageId (String): The ID of the email to read.
  • Example Return Value: A com.google.api.services.gmail.model.Message object.

searchEmails

  • Description: Searches for emails.
  • Parameters:
    • query (String): The search query (e.g., "from: is:unread").
  • Example Return Value: A list of com.google.api.services.gmail.model.Message objects.

downloadAttachment

  • Description: Downloads an attachment.
  • Parameters:
    • messageId (String): The ID of the email containing the attachment.
    • attachmentId (String): The ID of the attachment.
    • savePath (String): The local file path to save the attachment to.
  • Example Return Value: "Attachment downloaded successfully to <savePath>"