Headless Gmail

🚀 Headless Gmail MCP Server

The Headless Gmail MCP Server is a Google API-based service that enables interaction with Gmail accounts via the command line or other automated tools. It supports functions such as reading emails, retrieving email body content, and sending new emails.

🚀 Quick Start

Prerequisites

1. Register a Google Cloud account and create a project.
2. Enable the Gmail API.
3. Configure the OAuth consent screen.
4. Create an OAuth client ID (select the desktop app type).
5. Obtain access tokens and refresh tokens. The required scopes include:
   • https://www.googleapis.com/auth/gmail.readonly (for reading emails)
   • https://www.googleapis.com/auth/gmail.send (for sending emails)

Installation Steps

1. Clone the repository:

   git clone https://github.com/yourusername/mcp-headless-gmail.git
   cd mcp-headless-gmail
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables and set your Google API credentials:

   export GOOGLE_CLIENT_ID=your_client_id
   export GOOGLE_CLIENT_SECRET=your_client_secret
   export GOOGLE_REFRESH_TOKEN=your_refresh_token
   

4. Start the service:

   python3 server.py
   

✨ Features

Key Advantages

1. Fully Automated: No manual operation is required. It can be invoked via scripts or the command line.
2. High Efficiency: Optimized the API call process, ensuring high efficiency when handling a large number of emails.
3. Secure Design: Adopts a token authentication mechanism and supports the OAuth 2.0 protocol to ensure secure data transmission.
4. Good Scalability: Easy to integrate with other systems and quickly add more Gmail-related functions.

Functionalities

• Read Emails: Retrieve the email list, email content, and detailed information in the inbox.
• Get Email Body: Supports reading the body content of large-sized emails in chunks.
• Send Emails: Send new emails via the API, supporting both HTML and plain text formats.

📦 Installation

Prerequisites

1. Register a Google Cloud account and create a project.
2. Enable the Gmail API.
3. Configure the OAuth consent screen.
4. Create an OAuth client ID (select the desktop app type).
5. Obtain access tokens and refresh tokens. The required scopes include:
   • https://www.googleapis.com/auth/gmail.readonly (for reading emails)
   • https://www.googleapis.com/auth/gmail.send (for sending emails)

Installation Steps

1. Clone the repository:

   git clone https://github.com/yourusername/mcp-headless-gmail.git
   cd mcp-headless-gmail
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables and set your Google API credentials:

   export GOOGLE_CLIENT_ID=your_client_id
   export GOOGLE_CLIENT_SECRET=your_client_secret
   export GOOGLE_REFRESH_TOKEN=your_refresh_token
   

4. Start the service:

   python3 server.py
   

💻 Usage Examples

Basic Usage

# Clone the repository
git clone https://github.com/yourusername/mcp-headless-gmail.git
cd mcp-headless-gmail

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
export GOOGLE_CLIENT_ID=your_client_id
export GOOGLE_CLIENT_SECRET=your_client_secret
export GOOGLE_REFRESH_TOKEN=your_refresh_token

# Start the service
python3 server.py

Advanced Usage

# Build a Docker image
docker build -t mcp-headless-gmail .

# Run the container
docker run -d --name mcp-email-service mcp-headless-gmail

📚 Documentation

Docker Usage

Build the Image

# Base image
FROM python:3.8-slim

# Set the working directory
WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy the application code
COPY . .

# Environment variable configuration
ENV GOOGLE_CLIENT_ID=your_client_id \
    GOOGLE_CLIENT_SECRET=your_client_secret \
    GOOGLE_REFRESH_TOKEN=your_refresh_token

# Start command
CMD ["python3", "server.py"]

Run the Container

docker build -t mcp-headless-gmail .
docker run -d --name mcp-email-service mcp-headless-gmail

Claude Desktop Configuration

1. Add the following tools to Claude.yaml:

   tools:
     - name: gmail_get_recent_emails
       path: /api/gmail/recent
     - name: gmail_get_email_body
       path: /api/gmail/body
     - name: gmail_send_email
       path: /api/gmail/send
     - name: gmail_refresh_token
       path: /api/gmail/refresh-token
   

2. Use these tools in Claude:

   {
     "tool": "gmail_get_recent_emails",
     "args": {
       "access_token": "${GOOGLE_ACCESS_TOKEN}"
     }
   }
   

Cross - platform Release

1. Generate multi - platform images:

   docker buildx build --platform linux/amd64,linux/arm64 -t mcp-headless-gmail:multi .
   

2. Push the images to Docker Hub or other registries.

🔧 Technical Details

Security Considerations

• Always use HTTPS for data transmission.
• Do not submit credentials to public code repositories.
• Rotate access tokens regularly to ensure security.

📄 License

Please refer to the LICENSE file for details.