Gmail MCP Server

Gmail MCP Server

A powerful Model Context Protocol (MCP) server that enables Claude AI to directly interact with Gmail.

📖 Table of Contents

• Overview
• Key Features
• Quick Start
  • Prerequisites
  • Installation
  • Set up Google Cloud and OAuth credentials
  • First Run and Authentication
  • Configure Claude Desktop
• Available Tools
• Usage Examples
• Advanced Configuration
  • Environment Variables
  • SSE Server Mode
• Documentation
• Security Considerations
• Contributing
• License
• Acknowledgments

📋 Overview

The Gmail MCP Server is a comprehensive implementation that enables AI assistants like Claude to directly interact with Gmail through natural language. It exposes a rich set of tools for email management, enabling seamless integration between conversational AI and your inbox.

💡 Key Features

• Complete Email Management
  • Send plain text and HTML emails with attachments
  • Read emails with proper parsing of complex message structures
  • Search your inbox with Gmail's powerful query syntax
  • Create and update draft emails
  • Manage labels, read/unread status, and trash
  • Perform batch operations on multiple emails
• Advanced Integration
  • Modern Python codebase with async/await pattern
  • Comprehensive error handling and recovery
  • Detailed progress reporting
  • Secure OAuth authentication flow
  • Multiple transport modes (STDIO and SSE)
  • Support for different deployment scenarios

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• A Google Cloud project with the Gmail API enabled
• OAuth 2.0 credentials for the Gmail API

Installation

1. Clone the repository
   git clone https://github.com/yourusername/gmail-mcp-server.git cd gmail-mcp-server
2. Set up a virtual environment
   python -m venv venv # On Windows venv\Scripts\activate # On macOS/Linux source venv/bin/activate
3. Install dependencies
   pip install -r requirements.txt
4. Set up Google Cloud and OAuth credentialsVisit the Google Cloud Console to:
   • Create a new project
   • Enable the Gmail API
   • Set up OAuth consent screen
   • Create OAuth Client ID credentials (Desktop application)
   • Download credentials as credentials.json in project root

First Run and Authentication

Run the server once to authenticate:

This will open a browser window asking you to authenticate with your Google account. After authentication, a token.json file will be created and saved for future use.

Configure Claude Desktop

1. Edit your Claude Desktop configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the Gmail MCP server to the configuration:
   { "mcpServers": { "gmail": { "command": "python", "args": [ "/absolute/path/to/gmail-mcp-server/gmail_server.py" ] } } }
3. Save the file and restart Claude Desktop

Note: Replace "/absolute/path/to/gmail-mcp-server/gmail_server.py" with the actual absolute path to the gmail_server.py file in your cloned repository.

🧰 Available Tools

The Gmail MCP Server exposes the following tools to Claude:

Email Sending

• send_email - Send basic emails with text/HTML content
• send_email_with_attachment - Send emails with file attachments
• send_email_with_multiple_attachments - Send emails with multiple attachments

Email Reading

• read_email - Read the content of a specific email by ID
• get_unread_emails - Get a list of unread emails
• get_important_emails - Get emails marked as important
• get_emails_with_attachments - Get emails that have attachments
• get_recent_emails - Get emails from the last X days

Email Search and Organization

• search_emails - Search emails using Gmail's query syntax
• get_email_labels - List all Gmail labels/folders
• create_email_label - Create a new label
• delete_email_label - Delete an existing label
• label_email - Apply a label to an email
• remove_email_label - Remove a label from an email

Email Status Management

• mark_as_read - Mark an email as read
• mark_as_unread - Mark an email as unread
• delete_email - Move an email to trash

Draft Management

• create_email_draft - Create a new draft email
• update_email_draft - Update an existing draft
• list_email_drafts - List available drafts
• send_draft - Send an existing draft

Batch Operations

• batch_apply_label - Apply a label to multiple emails
• batch_delete_emails - Move multiple emails to trash

Account Information

• get_email_profile - Get Gmail profile information
• summarize_recent_emails - Create a summary of recent emails

💬 Usage Examples

Here are some example prompts for Claude:

🔧 Advanced Configuration

Environment Variables

The server supports multiple environment variables for customization:

SSE Server Mode

The server can be run in SSE (Server-Sent Events) mode for HTTP-based integration:

This starts the server on the specified port (default: 3000), making it accessible via HTTP.

📚 Documentation

• MCP Specification - Learn about the Model Context Protocol
• Gmail API Documentation - Reference for Gmail API capabilities
• Google Cloud OAuth - Details on authentication flows

🔒 Security Considerations

• The server uses OAuth 2.0 for secure Gmail API authentication
• All actions run locally on your machine - emails never pass through third-party servers
• Authentication tokens are stored locally and can be revoked at any time
• The server requires local file access only for reading attachments
• Claude always asks for confirmation before sending or deleting emails

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Google for the Gmail API
• Anthropic for Claude and the Model Context Protocol
• Contributors to the Python Gmail API client libraries