MCP.so
Sign In

MCP Headless Gmail Server

@baryhuang

Repository

About MCP Headless Gmail Server

A MCP (Model Context Protocol) server that provides get, send Gmails without local credential or token setup.

#mcp#gmail#google-suite#gmail-bot#ai-assistant#mcp-server

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "mcp-headless-gmail": {
      "command": "docker",
      "args": [
        "build",
        "-t",
        "mcp-headless-gmail",
        "."
      ]
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

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.

Frequently asked questions

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.

Comments

Basic information

Category

Communication

License

MIT

Transports

stdio

Author

baryhuang

More Communication MCP servers

Discord MCP Server

hanweg

MCP server for discord bot

161

Twilio MCP Monorepo

twilio-labs

Monorepo providing 1) OpenAPI to MCP Tool generator 2) Exposing all of Twilio's API as MCP Tools

108

Email sending MCP 💌

ykhli

The official MCP server to send emails and interact with Resend

549

slack-mcp-server

ubie-oss

A Slack MCP server

110

MCP Communicator (Telegram)

qpd-v

An MCP server that enables communication with users through Telegram. This server provides a tool to ask questions to users and receive their responses via a Telegram bot.

45