Gmail MCP Server

A Java-based Model Context Protocol (MCP) server that integrates with Gmail to enable natural language email queries via Claude Desktop. The server exposes tools to search emails by topic (e.g., "project deadlines") and read email content, using the Gmail API with secure OAuth2 authentication.

Features

• Search Emails: Find emails by topic, sender, or date using Gmail's query syntax (e.g., from:alice budget).
• Read Emails: Retrieve full email content (subject, sender, body) by ID.
• Secure Authentication: Uses OAuth2 with gmail.readonly scope for minimal access.
• MCP Integration: Communicates with Claude Desktop via Stdio using JSON-RPC 2.0.
• Robust Design: Includes error handling, logging, and input validation for production readiness.

Prerequisites

• Java 17: Ensure JDK 17 is installed (java --version).
• Maven: For dependency management (mvn --version).
• Google Cloud Project: With Gmail API enabled and OAuth2 credentials.
• Claude Desktop: Installed and configured for MCP (available from Anthropic).
• Operating System: Tested on Windows, macOS, and Linux.

Setup Instructions

1. Create Google Cloud Credentials

1. Go to the Google Cloud Console.
2. Create a new project (e.g., "Gmail MCP Server").
3. Enable the Gmail API:
   • Navigate to APIs & Services > Library.
   • Search for "Gmail API" and click Enable.
4. Create OAuth 2.0 credentials:
   • Go to APIs & Services > Credentials > Create Credentials > OAuth 2.0 Client IDs.
   • Select Desktop app as the application type.
   • Name the client (e.g., "Gmail MCP Client").
   • Download the credentials.json file.
5. Add http://localhost to authorized redirect URIs:
   • In Credentials, edit the OAuth 2.0 Client ID and add http://localhost under Authorized redirect URIs.

2. Clone or Set Up the Project

1. Clone the repository (or create a new Maven project):

   git clone <repository-url>
   cd gmail-mcp-server
   

   Alternatively, create a new Maven project and copy the provided files:
   • src/main/java/com/swiftbeard/gmailmcp/GmailMcpServer.java
   • pom.xml
   • src/main/resources/credentials.json (from Google Cloud)
   • src/main/resources/logback.xml
2. Place credentials.json in src/main/resources/.
3. Verify the project structure:

   gmail-mcp-server/
   ├── pom.xml
   ├── src/
   │   ├── main/
   │   │   ├── java/
   │   │   │   └── com/swiftbeard/gmailmcp/
   │   │   │       └── GmailMcpServer.java
   │   │   ├── resources/
   │   │   │   ├── credentials.json
   │   │   │   └── logback.xml
   

3. Build the Project

1. Install dependencies and build the project:

   mvn clean install
   

2. The build will generate a shaded JAR: target/gmail-mcp-server-1.0-SNAPSHOT.jar.

4. Run the Server

1. Start the server:

   java -jar target/gmail-mcp-server-1.0-SNAPSHOT.jar
   

2. On first run, the server opens a browser for OAuth2 authentication:
   • Log in with your Gmail account.
   • Grant permission for the app to read emails (uses gmail.readonly scope).
   • Tokens are saved to ~/.gmail-mcp/tokens for subsequent runs.
3. The server runs in Stdio mode, waiting for MCP requests from Claude Desktop.

5. Configure Claude Desktop

1. Install Claude Desktop from Anthropic’s website.
2. Locate or create the MCP configuration file (e.g., ~/.cursor/mcp.json or Claude’s settings file).
3. Add the Gmail MCP server configuration:

   {
     "mcpServers": {
       "gmail": {
         "command": "java",
         "args": ["-jar", "/full/path/to/gmail-mcp-server-1.0-SNAPSHOT.jar"]
       }
     }
   }
   

   Replace /full/path/to/gmail-mcp-server-1.0-SNAPSHOT.jar with the absolute path to your JAR file (e.g., /home/user/gmail-mcp-server/target/gmail-mcp-server-1.0-SNAPSHOT.jar).
4. Save the file and restart C

... View full README on GitHub