jnpacker/gmail-mcp-server

Gmail MCP Server

A purpose-built Model Context Protocol (MCP) server for Gmail integration, allowing AI assistants to review unread emails and perform email management operations.

Features

• List Unread Emails: Retrieve unread emails from Gmail inbox with optional subject filtering
• Email Content: Access complete email content including headers, body, and metadata
• Delete Emails: Permanently delete emails by ID
• Archive Emails: Archive emails (remove from inbox) by ID

Installation

1. Clone this repository:

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

2. Install dependencies:

pip install -r requirements.txt

3. Set up Google OAuth 2.0 credentials:
   • Go to Google Cloud Console
   • Create a new project or select an existing one
   • Enable the Gmail API
   • Create OAuth 2.0 credentials (Desktop application)
   • Download the credentials JSON file and save as credentials.json in the project root

Start the server:

python -m gmail_mcp_server.server

MCP Configuration

To use this Gmail MCP server with Claude or gemini-cli, you need to configure a .mcp.json file. This file tells the AI assistant how to connect to your MCP server.

.mcp.json Configuration

Create a .mcp.json file in your home directory or project directory with the following configuration:

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["-m", "gmail_mcp_server.server"],
      "cwd": "/path/to/gmail-mcp-server"
    }
  }
}

Configuration Details:

• command: The Python interpreter to use
• args: Arguments to pass to the Gmail MCP server module
• cwd: The working directory where the Gmail MCP server is installed

For Claude Desktop: Place the .mcp.json file in your Claude Desktop configuration directory:

• macOS: ~/Library/Application Support/Claude/
• Windows: %APPDATA%\Claude\
• Linux: ~/.config/claude/

For gemini-cli: Place the .mcp.json file in your home directory or specify the path when running gemini-cli.

Example Usage

Once configured, you can use the Gmail MCP server with AI assistants with these commands:

Basic Email Management

• "list emails" - Quick command to show all unread emails with smart categorization
• "Show me my unread emails" - Full command to display unread emails
• "List emails with 'urgent' in the subject" - Filter emails by subject content

Email Actions by Position Number

• "delete email 1, 4, 6" - Delete specific emails using their position numbers from the email list
• "archive email 3" - Archive a single email by position number
• "delete emails 2, 5, 7" - Delete multiple emails by their list positions

Bulk Operations by Category

• "archive all meeting updates" - Archive all emails in the "Meeting Updates" group
• "delete all social media notifications" - Delete all emails in the "Social Media" group
• "apply recommendations" - Execute all suggested actions (archive/delete) that the AI has identified

Advanced Filtering

• "Delete the email with ID 123456789abcdef" - Delete by specific Gmail message ID
• "Archive all emails from john@example.com" - Archive emails from specific sender

AI Assistant Commands

This project includes pre-configured command files for different AI assistants to provide intelligent Gmail management capabilities:

Claude CLI

The .claude/commands/emails.md file provides comprehensive Gmail management instructions for Claude CLI. This command enables:

• Smart email categorization and grouping
• Priority rating (Minor/Good to Know/Major)
• Automated action suggestions (archive/delete)
• Dynamic email summaries
• Intelligent filtering for different email types

Gemini CLI

The .gemini/commands/emails.toml file provides the same Gmail management capabilities for Gemini CLI users. The configuration includes:

• Email listing and analysis workflows
• Dynamic grouping based on email content
• Priority-based action recommendations
• Support for bulk operations and individual email actions

Cursor

Coming soon - Cursor integration is planned for future implementation.

Available Tools

1. list_unread_emails

Lists unread emails in Gmail inbox with optional filtering.

Parameters:

• subject_filter (optional): Filter emails containing specific text in subject
• max_results (optional): Maximum number of emails to return (default: 50)

Example:

{
  "subject_filter": "important",
  "max_results": 10
}

2. delete_email

Permanently deletes an email by ID.

Parameters:

• message_id (required): Gmail message ID to delete

Example:

{
  "message_id": "123456789abcdef"
}

3. archive_email

Archives an email (removes from inbox) by ID.

Parameters:

• message_id (required): Gmail message ID to archive

Example:

{
  "message_id": "123456789abcdef"
}

Authentication

Initial Setup

On first run, the server requires authentication. Use the provided authentication helper:

gmail-mcp-auth

This will:

1. Open a browser window for OAuth 2.0 authentication
2. Request permission to access your Gmail account
3. Save the authentication token to token.json for future use

If you installed in development mode, you can also run:

python -m gmail_mcp_server.auth

How It Works

• The server checks for an existing authentication token (token.json) on startup
• If the token exists and is valid, the server uses it automatically
• If the token is expired but has a refresh token, it refreshes automatically
• If no token exists, the server will request authentication using the gmail-mcp-auth command

Required Gmail API Scopes

• https://www.googleapis.com/auth/gmail.readonly - Read emails
• https://www.googleapis.com/auth/gmail.modify - Delete and archive emails

Security Notes

• Keep your credentials.json and token.json files secure
• These files are automatically ignored by git
• The server only requests minimal required permissions
• All operations are performed through official Gmail API

Development

Install in development mode:

pip install -e .

Run the server:

gmail-mcp-server