# mcp-headless-gmail

> MCP Server

This repository provides a Docker-ready MCP server for headless Gmail access, enabling remote email retrieval and sending without local credentials or browser setup, using decoupled architecture and automatic token refresh.

## Overview

- **Category:** Communication
- **Language:** Python
- **Stars:** 55
- **Forks:** 3
- **Owner:** baryhuang
- **GitHub:** https://github.com/baryhuang/mcp-headless-gmail
- **Created:** 2025-03-20T06:12:47+00:00
- **Updated:** 2025-03-27T13:09:30+00:00
- **Source:** https://model-context-protocol.com/servers/headless-gmail-access-remote-email-server

## Setup

## Setup

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

2. Install dependencies:
   ```bash
   pip install -e .
   ```

3. Build the Docker image:
   ```bash
   docker build -t mcp-headless-gmail .
   ```

4. Create a new builder instance (if you haven't already):
   ```bash
   docker buildx create --use
   ```

5. Build and push the image for multiple platforms:
   ```bash
   docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .
   ```

6. Verify the image is available for the specified platforms:
   ```bash
   docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest
   ```

7. Obtain Google API credentials by going to the Google Cloud Console, creating a new project, enabling the Gmail API, configuring OAuth consent screen, creating OAuth client ID credentials, and saving the client ID and client secret.

8. Use OAuth 2.0 to obtain access and refresh tokens with the scopes `https://www.googleapis.com/auth/gmail.readonly` and `https://www.googleapis.com/auth/gmail.send`.

## Tools

## Available Tools

1. Get most recent emails from Gmail (retrieves emails with the first 1k characters of the body).
2. Get full email body content (retrieves content in 1k chunks using offset parameter).
3. Send emails through Gmail (sends emails to specified recipients).
4. Refresh access tokens separately (refreshes access tokens using refresh token, client ID, and client secret).
5. Automatic refresh token handling (automatically refreshes tokens when they expire).