MCP Headless Gmail Server

What is MCP Headless Gmail Server?

A Model Context Protocol (MCP) server that provides get, send, and refresh Gmail functionality without requiring local credential or token setup. It is designed for headless, remote environments and decouples credential storage from server implementation.

How to use MCP Headless Gmail Server?

Install via pip install -e . or use the Docker image buryhuang/mcp-headless-gmail:latest. Configure an MCP client like Claude Desktop with either the Docker or npx command shown in the README. Provide your Google API credentials (client ID, client secret, access token, refresh token) via tool calls. Start by refreshing the token with gmail_refresh_token, then use tools such as get_recent_emails, get_email_body, and send_email.

Key features of MCP Headless Gmail Server

• Get recent emails with first 1k characters of body.
• Retrieve full email body in 1k-character chunks via offset.
• Send emails through Gmail with plain text or HTML body.
• Refresh access tokens separately or automatically when expired.
• Run completely headless in remote environments (no browser, no local files).
• Docker-ready for isolated, one-click deployment.

Use cases of MCP Headless Gmail Server

• Automate reading and responding to emails from an AI assistant.
• Send Gmail messages directly from MCP-enabled clients like Claude Desktop.
• Integrate Gmail access into marketing or notification workflows without local credential storage.
• Deploy a stateless Gmail service in containerised or cloud environments.

FAQ from MCP Headless Gmail Server

What are the prerequisites?

Python 3.10 or higher and Google API credentials (client ID, client secret, access token, and refresh token).

How do I obtain Google API credentials?

Create a project in the Google Cloud Console, enable the Gmail API, configure the OAuth consent screen, create an OAuth client ID (Desktop app type), and use OAuth 2.0 to obtain tokens with scopes gmail.readonly and gmail.send.

How does token refresh work?

The server provides a gmail_refresh_token tool that accepts either full credentials or just a refresh token with client ID/secret. It returns a new access token. Automatic refresh is also handled by the underlying Google API client when the access token expires.

Can this server run inside Docker?

Yes. The Docker image can be built with docker build -t mcp-headless-gmail . and run with a docker run command. Configuration for Claude Desktop using Docker is provided in the README.

What scopes are required for the Gmail API?

The server requires https://www.googleapis.com/auth/gmail.readonly for reading emails and https://www.googleapis.com/auth/gmail.send for sending emails.