@mjamei/gmail-mcp

Gmail AutoAuth MCP Server

A Model Context Protocol (MCP) server for Gmail integration in any agentic workflow.

Features

• Send emails with subject, content, attachments, and recipients
• Reply to emails (with support for Reply All)
• Read email messages by ID with advanced MIME structure handling
• View email attachments information (filenames, types, sizes)
• Search emails with various criteria (subject, sender, date range)
• List all available Gmail labels (system and user-defined)
• List emails in inbox, sent, or custom labels
• Mark emails as read/unread
• Move emails to different labels/folders
• Delete emails
• Full integration with Gmail API
• Simple OAuth2 authentication flow with auto browser launch
• Support for both Desktop and Web application credentials
• Global credential storage for convenience

Installation & Authentication

Installing via npx

npx -y @mjamei/gmail-mcp

Installing Manually

1. Create a Google Cloud Project and obtain credentials:

   a. Create a Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project or select an existing one
   • Enable the Gmail API for your project

   b. Create OAuth 2.0 Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose either "Desktop app" or "Web application" as application type
   • Give it a name and click "Create"
   • For Web application, add http://localhost:3000/oauth2callback to the authorized redirect URIs
   • Download the JSON file of your client's OAuth keys
   • Rename the key file to gcp-oauth.keys.json

2. Run Authentication:

   You can authenticate in two ways:

   a. Global Authentication (Recommended):

   # First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
   mkdir -p ~/.gmail-mcp
   mv gcp-oauth.keys.json ~/.gmail-mcp/
   
   # Run authentication from anywhere
   npx @gongrzhe/server-gmail-autoauth-mcp auth

   b. Local Authentication:

   # Place gcp-oauth.keys.json in your current directory
   # The file will be automatically copied to global config
   npx @gongrzhe/server-gmail-autoauth-mcp auth

   The authentication process will:

   • Look for gcp-oauth.keys.json in the current directory or ~/.gmail-mcp/
   • If found in current directory, copy it to ~/.gmail-mcp/
   • Open your default browser for Google authentication
   • Save credentials as ~/.gmail-mcp/credentials.json

   Note:

   • After successful authentication, credentials are stored globally in ~/.gmail-mcp/ and can be used from any directory
   • Both Desktop app and Web application credentials are supported
   • For Web application credentials, make sure to add http://localhost:3000/oauth2callback to your authorized redirect URIs

Docker Support

If you prefer using Docker:

1. Authentication:

docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth

2. Usage:

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "mcp-gmail:/gmail-server",
        "-e",
        "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
        "mcp/gmail"
      ]
    }
  }
}

Available Tools

The server provides the following tools that can be used through Claude Desktop:

1. Send Email (send_email)

Sends a new email immediately.

{
  "to": ["[e-mail]"],
  "subject": "Meeting Tomorrow",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "cc": ["[e-mail]"],
  "bcc": ["[e-mail]"]
}

2. Reply to Email (reply_to_email)

Replies to an existing email thread, with support for Reply All.

{
  "messageId": "182ab45cd67ef",
  "body": "Thanks for your email. I'll review and get back to you soon.",
  "replyAll": true  // Optional, defaults to false
}

The reply will:

• Maintain the email thread
• Automatically handle "Re:" subject prefix
• Include proper email headers for threading
• Support both simple reply (to sender) and reply-all (to all recipients)
• Handle complex email addresses (e.g., "John Doe [e-mail]")

3. Draft Email (draft_email)

Creates a draft email without sending it.

{
  "to": ["[e-mail]"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["[e-mail]"]
}

4. Read Email (read_email)

Retrieves the content of a specific email by its ID.

{
  "messageId": "182ab45cd67ef"
}

5. Search Emails (search_emails)

Searches for emails using Gmail search syntax.

{
  "query": "from:[e-mail] after:2024/01/01 has:attachment",
  "maxResults": 10
}

6. Modify Email (modify_email)

Adds or removes labels from emails (move to different folders, archive, etc.).

{
  "messageId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

7. Delete Email (delete_email)

Permanently deletes an email.

{
  "messageId": "182ab45cd67ef"
}

8. List Email Labels (list_email_labels)

Retrieves all available Gmail labels.

{}

Advanced Search Syntax

The search_emails tool supports Gmail's powerful search operators:

Operator	Example	Description
from:	from:[e-mail]	Emails from a specific sender
to:	to:[e-mail]	Emails sent to a specific recipient
subject:	subject:"meeting notes"	Emails with specific text in the subject
has:attachment	has:attachment	Emails with attachments
after:	after:2024/01/01	Emails received after a date
before:	before:2024/02/01	Emails received before a date
is:	is:unread	Emails with a specific state
label:	label:work	Emails with a specific label

You can combine multiple operators: from:[e-mail] after:2024/01/01 has:attachment

Advanced Features

Email Threading and Replies

The server implements proper email threading:

• Maintains conversation threads using Message-ID, References, and In-Reply-To headers
• Automatically formats reply subjects with "Re:" prefix
• Handles complex email address formats (with display names)
• Supports both direct replies and reply-all functionality
• Preserves thread IDs for proper conversation grouping in Gmail

Email Content Extraction

The server intelligently extracts email content from complex MIME structures:

• Prioritizes plain text content when available
• Falls back to HTML content if plain text is not available
• Handles multi-part MIME messages with nested parts
• Processes attachments information (filename, type, size)
• Preserves original email headers (From, To, Subject, Date)

International Character Support

The server fully supports non-ASCII characters in email subjects and content, including:

• Turkish, Chinese, Japanese, Korean, and other non-Latin alphabets
• Special characters and symbols
• Proper encoding ensures correct display in email clients

Security Notes

• OAuth credentials are stored securely in your local environment (~/.gmail-mcp/)
• The server uses offline access to maintain persistent authentication
• Never share or commit your credentials to version control
• Regularly review and revoke unused access in your Google Account settings
• Credentials are stored globally but are only accessible by the current user

Troubleshooting

1. OAuth Keys Not Found

   • Make sure gcp-oauth.keys.json is in either your current directory or ~/.gmail-mcp/
   • Check file permissions

2. Invalid Credentials Format

   • Ensure your OAuth keys file contains either web or installed credentials
   • For web applications, verify the redirect URI is correctly configured

3. Port Already in Use

   • If port 3000 is already in use, please free it up before running authentication
   • You can find and stop the process using that port

Contributing

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

License

MIT

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.