Gmail MCP Server

A Model Context Protocol (MCP) server that provides Gmail integration capabilities through a clean, async API.

Features

• 🔍 Search emails with Gmail's powerful search syntax

• 📧 Send emails with support for CC/BCC

• 📋 Get recent emails from inbox

• 📄 Get detailed email content including full body

• 🏷️ List Gmail labels (system and custom)

• 📁 Get emails by label (INBOX, STARRED, etc.)

• 💚 Health check to verify server and API connectivity

• ⏱️ Timeout protection for all API calls

• 🔄 Token refresh capability (requires client credentials)

Quick Start

1. Install Dependencies

2. Set up Gmail API Credentials

1. Go to Google Cloud Console

2. Create a new project or select existing one

3. Enable the Gmail API

4. Create OAuth 2.0 credentials

5. Download the credentials file

3. Get Access and Refresh Tokens

You'll need to obtain OAuth 2.0 tokens for Gmail API access. You can use the Google OAuth 2.0 playground or create a simple script to get these tokens.

4. Run the Server

5. Test the Server

Available Tools

search_emails

Search Gmail using Gmail's search syntax.

Input:

Examples:

• after:2025/06/17 - Emails after specific date

• from:example@gmail.com - Emails from specific sender

• subject:meeting - Emails with specific subject

• is:unread - Unread emails

• has:attachment - Emails with attachments

get_recent_emails

Get the most recent emails from inbox.

Input:

get_email_details

Get complete details of a specific email including full body content.

Input:

send_email

Send an email via Gmail.

Input:

list_gmail_labels

List all Gmail labels including system and user-created labels.

Input:

get_emails_by_label

Fetch emails that belong to a specific Gmail label.

Input:

health_check

Check the health and connectivity of the Gmail MCP server.

Input:

Configuration

Environment Variables

You can set these environment variables instead of passing tokens as arguments:

• GMAIL_ACCESS_TOKEN - Your Gmail API access token

• GMAIL_REFRESH_TOKEN - Your Gmail API refresh token

Server Settings

The server is configured with:

• Port: 8010

• Log level: INFO

• Cache expiration: 60 seconds

• Gmail API timeout: 30 seconds

Error Handling

The server includes comprehensive error handling:

• Timeout protection for all API calls

• Graceful handling of expired tokens

• Detailed error messages for debugging

• Fallback responses for failed operations

Security Considerations

• Never commit tokens to version control

• Use environment variables for sensitive data

• Consider implementing token refresh for long-running sessions

• Validate all input parameters

Troubleshooting

Common Issues

1. "Invalid credentials" error

   • Check that your access token is valid and not expired

   • Verify your refresh token is correct

2. "Permission denied" error

   • Ensure your Gmail API credentials have the necessary scopes

   • Check that the Gmail API is enabled in your Google Cloud project

3. "Timeout" errors

   • The server has a 30-second timeout for Gmail API calls

   • For large email searches, try reducing max_results

Testing

Run the test script to verify your setup:

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

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