📌Overview

Purpose: The framework serves to integrate Gmail functionalities within Claude Desktop, enabling AI assistants to manage emails seamlessly through natural language interactions.

Overview: The Gmail AutoAuth MCP Server is designed for efficient Gmail management. With auto authentication support, it allows users to perform various email operations easily, enhancing interaction through a natural language interface.

Key Features:

Email Management: Send and read emails, handle attachments, and organize emails with customizable labels.
Advanced Search Capabilities: Utilize Gmail’s search features to find emails based on multiple criteria such as sender, subject, and date range.
International Character Support: Full compatibility with non-ASCII characters in email subjects and content, allowing a diverse range of users to interact without language barriers.
OAuth2 Authentication: Easy integration with secure authentication processes to manage Gmail access without manual credential handling.
Global Credential Storage: Conveniently store authentication credentials locally, facilitating smooth and secure access across multiple sessions.

Gmail AutoAuth MCP Server

A Model Context Protocol (MCP) server for Gmail integration in Claude Desktop with auto authentication support. This server enables AI assistants to manage Gmail through natural language interactions.

Features

Send emails with subject, content, attachments, and recipients.
Full support for international characters in subject lines and email content.
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 Smithery

To install Gmail AutoAuth for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude

Installing Manually

Create a Google Cloud Project and obtain credentials:
- Create a new project or select an existing one in Google Cloud Console.
- Enable the Gmail API for your project.
- Under "APIs & Services" > "Credentials":
  - Click "Create Credentials" > "OAuth client ID".
  - Choose "Desktop app" or "Web application" as application type.
  - Add http://localhost:3000/oauth2callback to the authorized redirect URIs if using Web application.
  - Download the JSON file and rename it to gcp-oauth.keys.json.

Run Authentication:

Global Authentication (Recommended):

mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/
npx @gongrzhe/server-gmail-autoauth-mcp auth

Local Authentication:

npx @gongrzhe/server-gmail-autoauth-mcp auth

Configure in Claude Desktop:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@gongrzhe/server-gmail-autoauth-mcp"
      ]
    }
  }
}

Docker Support

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

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

Send Email (`send_email`)

Sends a new email immediately.

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

Draft Email (`draft_email`)

Creates a draft email without sending it.

{
  "to": ["recipient@example.com"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["manager@example.com"]
}

Read Email (`read_email`)

Retrieves the content of a specific email by its ID.

{
  "messageId": "182ab45cd67ef"
}

Search Emails (`search_emails`)

Searches for emails using Gmail search syntax.

{
  "query": "from:sender@example.com after:2024/01/01 has:attachment",
  "maxResults": 10
}

Modify Email (`modify_email`)

Adds or removes labels from emails.

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

Delete Email (`delete_email`)

Permanently deletes an email.

{
  "messageId": "182ab45cd67ef"
}

List Email Labels (`list_email_labels`)

Retrieves all available Gmail labels.

{}

Advanced Features

Email Content Extraction

The server intelligently extracts email content from complex MIME structures prioritizing plain text content, falling back to HTML content if necessary, and processing attachments information.

International Character Support

The server fully supports non-ASCII characters in email subjects and content.

Security Notes

OAuth credentials are stored securely.
The server uses offline access to maintain persistent authentication.
Regularly review and revoke unused access in your Google Account settings.

Troubleshooting

OAuth Keys Not Found: Verify the location of gcp-oauth.keys.json.
Invalid Credentials Format: Check that your OAuth keys file is formatted correctly.
Port Already in Use: Ensure port 3000 is free.

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.

Gmail-MCP-Server