Gmail Headless

Gmail Headless

Remote hostable MCP server that can get and send Gmail messages without local credential or file system setup.

54
Stars
29
Forks
0
Releases

Overview

An MCP server that provides Gmail read and send capabilities without requiring local credentials. It runs headless in remote environments, with a decoupled architecture where clients complete the OAuth flow and pass credentials as MCP context to the server. The server focuses on Gmail-only functionality, excluding other Google services like Calendar, and is designed for Docker-ready and NPM packaging. It supports retrieving recent emails with the first 1,000 characters of the body, and retrieving full email content in 1,000-character chunks using an offset. It can send emails through Gmail and includes a token refresh workflow with a dedicated tool to refresh tokens and automatic refresh handling. Prerequisites include Python 3.10 or higher and Google API credentials. The project uses the google-api-python-client library and can be published cross-platform via Docker buildx. Credentials are provided in MCP tool calls as context rather than environment variables to maintain separation between credential storage and server implementation. A security note emphasizes that credentials are required by the server and should be kept secure.

Details

Owner
baryhuang
Language
Python
License
MIT License
Updated
2025-12-07

Features

Get most recent emails

Retrieve recent Gmail messages with the first 1,000 characters of the body.

Get full email body content in chunks

Fetch full email content in 1,000-character chunks using an offset.

Send emails through Gmail

Send messages via the Gmail API using provided recipient, subject, and body.

Refresh access tokens separately

Refresh access tokens using a refresh token, client ID, and client secret.

Automatic refresh token handling

Automatically refresh tokens when needed via the Google API client.

Headless remote operation

Run entirely headless in remote environments without browser or local file access.

Decoupled credential handling

Clients complete OAuth flow and pass credentials as MCP context to the server.

Docker/NPM packaging

Container-ready Docker image and npm package for easy deployment and distribution.

Audience

DevelopersBuild remote apps needing Gmail access without storing credentials locally via MCP.

Tags

GmailGmail APIMCPHeadlessOAuthToken refreshDockerNPMPythonRemote