Gmail MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Gmail functionality through FastMCP. This server enables AI assistants like Claude to interact with Gmail accounts, manage emails, send messages, and perform various Gmail operations using OAuth2 authentication via Nango.

Features

Core Gmail Operations

• Message Management: List, search, read, and delete emails
• Send Emails: Send messages with or without attachments
• Message Actions: Mark messages as read, manage labels
• Advanced Search: Filter by sender, subject, date, attachments, read status
• Account Statistics: Get Gmail account overview and metrics
• Thread Support: Handle Gmail conversation threads
• Attachment Support: Send emails with file attachments

Authentication & Security

• OAuth2 Integration: Secure authentication via Nango
• Token Management: Automatic token refresh and validation
• Multi-account Support: Handle multiple Gmail accounts
• Secure Credential Storage: Environment-based configuration

Prerequisites

• Python 3.13+
• Gmail account with API access enabled
• Google Cloud Project with Gmail API enabled
• Nango account for OAuth2 management (optional but recommended)

Installation

1. Clone or create the project structure:

mkdir gmail-mcp-server
cd gmail-mcp-server

2. Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -e .

Configuration

Environment Variables

Create a .env file in the project root:

# Nango Configuration (Recommended)
NANGO_BASE_URL=https://api.nango.dev
NANGO_SECRET_KEY=your_nango_secret_key
NANGO_CONNECTION_ID=your_NANGO_CONNECTION_ID
NANGO_INTEGRATION_ID=google

# Alternative: Direct Google OAuth (if not using Nango)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REFRESH_TOKEN=your_refresh_token

Google Cloud Setup

1. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project or select existing one

2. Enable Gmail API:

   • Navigate to "APIs & Services" > "Library"
   • Search for "Gmail API" and enable it

3. Create OAuth2 Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth 2.0 Client IDs"
   • Choose "Desktop application" or "Web application"
   • Note the Client ID and Client Secret

4. Configure OAuth Scopes:

   • Add the following scopes:
     • https://www.googleapis.com/auth/gmail.readonly
     • https://www.googleapis.com/auth/gmail.send
     • https://www.googleapis.com/auth/gmail.modify

Nango Setup (Recommended)

1. Create Nango Account: Sign up at nango.dev
2. Create Google Integration: Set up Google OAuth2 integration
3. Configure Connection: Create a connection for your Gmail account
4. Get Credentials: Note your connection ID and provider config key

Claude Desktop Configuration

Add this configuration to your Claude Desktop config file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

With Nango

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["git+https://github.com/ampcome-mcps/gmail-mcp.git"],
      "env": {
        "NANGO_BASE_URL": "https://api.nango.dev",
        "NANGO_SECRET_KEY": "your_nango_secret_key",
        "NANGO_CONNECTION_ID": "your_nango_connection_id",
        "NANGO_INTEGRATION_ID": "google-mail"
      }
    }
  }
}

Notes:

• On Windows, use backslashes in paths: C:\\path\\to\\your\\gmail-mcp-server\\main.py
• For virtual environment on Windows: .venv\\Scripts\\python.exe
• Replace placeholder values with your actual credentials

Available Tools

The MCP server provides the following tools for Claude:

Message Operations

• gmail_list_messages - List Gmail messages with optional search query
• gmail_get_message - Get details of a specific message
• gmail_search_messages - Advanced search with multiple criteria
• gmail_send_message - Send a new email message
• gmail_send_message_with_attachment - Send email with file attachment

Message Management

• gmail_mark_as_read - Mark messages as read
• gmail_delete_messages - Delete messages permanently

Account Information

• gmail_get_stats - Get Gmail account statistics and overview

Usage Examples

Once configured with Claude, you can use natural language commands like:

Basic Operations

• "Show me my latest 10 emails"
• "Search for emails from john@example.com sent this week"
• "Get the full content of message ID xyz123"
• "Send an email to sarah@example.com with subject 'Meeting Tomorrow'"

Advanced Operations

• "Find all unread emails with attachments from the last 7 days"
• "Mark all emails from newsletter@company.com as read"
• "Delete the email with ID abc456"
• "Send a report to my manager with the quarterly-report.pdf attachment"
• "Show me my Gmail account statistics"

Search Capabilities

• "Find emails about 'project alpha' from last month"
• "Show unread emails from important@client.com"
• "List emails with attachments sent after 2024/01/01"

Project Structure

gmail-mcp-server/
├── main.py                 # FastMCP server implementation
├── gmail_auth.py           # Gmail OAuth2 authentication
├── gmail_operations.py     # Gmail client operations
├── pyproject.toml         # Project configuration
├── .env                   # Environment variables (create from template)
├── .env.example          # Environment template
├── README.md             # This file
├── uv.lock              # Dependency lock file
└── .gitignore           # Git ignore rules

Running the Server

With Claude Desktop

The server automatically starts when Claude Desktop loads the configuration.

Standalone Testing

For development and testing:

python main.py

Tool Specifications

gmail_list_messages

# Parameters:
- query: str = ""              # Gmail search query
- max_results: int = 10        # Max messages (1-100)

# Returns:
{
  "success": bool,
  "count": int,
  "messages": [
    {
      "id": "message_id",
      "from": "sender@example.com",
      "subject": "Email subject",
      "date": "2024-01-01",
      "snippet": "Preview text...",
      "is_unread": bool
    }
  ]
}

gmail_search_messages

# Parameters:
- sender: str = None           # Filter by sender
- subject: str = None          # Filter by subject
- after_date: str = None       # After date (YYYY/MM/DD)
- before_date: str = None      # Before date (YYYY/MM/DD)
- has_attachment: bool = False # Filter with attachments
- is_unread: bool = False      # Filter unread only
- max_results: int = 20        # Max results (1-100)

gmail_send_message

# Parameters:
- to: str                      # Recipient email (required)
- subject: str                 # Email subject (required)
- body: str                    # Email content (required)
- cc: str = ""                # CC recipients
- bcc: str = ""               # BCC recipients

# Returns:
{
  "success": bool,
  "message_id": "sent_message_id",
  "to": "recipient@example.com",
  "subject": "Email subject"
}

Development

Key Components

1. main.py: FastMCP server with tool definitions
2. gmail_auth.py: OAuth2 authentication handling
3. gmail_operations.py: Gmail API client wrapper
4. Nango Integration: Secure credential management

Adding New Features

1. Add Gmail Operation: Extend GmailClient class in gmail_operations.py
2. Define MCP Tool: Add @mcp.tool() decorator in main.py
3. Add Validation: Include parameter validation and error handling
4. Update Documentation: Add usage examples and tool specifications

Dependencies

• google-api-python-client - Official Google API client
• google-auth - Google authentication library
• mcp[cli] - Model Context Protocol framework
• python-dotenv - Environment variable management
• pydantic - Data validation
• requests - HTTP client for Nango integration

Troubleshooting

Common Issues

1. Authentication Errors:

   • Verify Nango credentials are correct
   • Check Gmail API is enabled in Google Cloud
   • Ensure OAuth scopes are properly configured

2. Permission Errors:

   • Verify OAuth2 scopes include required permissions
   • Check if Gmail account has necessary access

3. Message Not Found:

   • Ensure message IDs are valid Gmail message IDs
   • Check if messages haven't been deleted

4. Rate Limiting:

   • Gmail API has quotas and rate limits
   • Implement retry logic for production use

Debug Mode

Enable debug logging by setting environment variable:

export GMAIL_MCP_DEBUG=true

Testing Nango Connection

# Test script to verify Nango setup
from gmail_auth import get_connection_credentials

try:
    result = get_connection_credentials("your_connection_id", "google")
    print("Nango connection successful:", result.keys())
except Exception as e:
    print("Nango connection failed:", e)

Security Considerations

1. Environment Variables: Never commit .env files with credentials
2. Token Storage: Tokens are handled securely by Nango
3. API Quotas: Monitor Gmail API usage to avoid quota exhaustion
4. Scope Limitations: Use minimal required OAuth scopes
5. Access Control: Limit MCP server access to authorized clients

Performance Optimization

1. Batch Operations: Use batch requests when possible
2. Caching: Implement message caching for frequently accessed data
3. Pagination: Handle large result sets with proper pagination
4. Connection Pooling: Reuse HTTP connections for API calls

Error Handling

The server implements comprehensive error handling:

• Validation Errors: Parameter validation with descriptive messages
• API Errors: Gmail API error handling and retry logic
• Authentication Errors: Token refresh and re-authentication
• Network Errors: Connection timeout and retry mechanisms

Contributing

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

License

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

Support

For support and questions:

• Check the troubleshooting section
• Review Gmail API documentation: Gmail API Guide
• Open an issue in the project repository
• Check Nango documentation: Nango Docs

Acknowledgments

• FastMCP: Simplified MCP server implementation
• Google API Python Client: Official Gmail API integration
• Nango: OAuth2 authentication management
• Model Context Protocol: Standard for AI tool integration