Headless Gmail MCP Server

CommunicationJavaScript

Access and send Gmail emails without local credential setup or browser dependencies

Available Tools

refresh_token

Refreshes the Google access token using the refresh token, client ID, and client secret

google_refresh_tokengoogle_client_idgoogle_client_secretgoogle_access_token

get_recent_emails

Retrieves recent emails from Gmail with the first 1k characters of each email body

google_access_tokenmax_resultsunread_only

get_email_content

Retrieves email content in 1k chunks using message ID and offset

google_access_tokenmessage_idthread_idoffset

send_email

Sends an email through Gmail

google_access_tokentosubjectbodyccbcc

Headless Gmail provides a streamlined way to interact with Gmail through a Model Context Protocol server that operates completely headless in remote environments. Unlike other Gmail solutions, it requires no browser access or local file storage, making it ideal for containerized deployments. The server enables a decoupled architecture where clients can complete OAuth flows independently and pass credentials as context, creating a clean separation between credential storage and implementation. Built on the reliable google-api-python-client library, it offers focused Gmail functionality for retrieving and sending emails.

Overview

Headless Gmail is a Model Context Protocol server that provides Gmail access capabilities without requiring local credential storage or browser dependencies. This makes it perfect for containerized environments and remote deployments where traditional Gmail access methods would be challenging.

Installation Options

Docker Installation (Recommended)

The simplest way to use Headless Gmail is through its Docker image:

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "buryhuang/mcp-headless-gmail:latest"
      ]
    }
  }
}

NPM Installation

Alternatively, you can use the NPM package:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@peakmojo/mcp-server-headless-gmail"
      ]
    }
  }
}

Manual Installation

If you prefer to install from source:

Clone the repository:

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

Install dependencies:
```
pip install -e .
```
Start the server:
```
mcp-server-headless-gmail
```

Authentication

Before using the Gmail functionality, you'll need Google API credentials. The server is designed to keep credential management separate from the implementation, so you'll need to provide:

Google Client ID
Google Client Secret
Google Access Token
Google Refresh Token

These credentials are passed with each request rather than being stored on the server.

Usage

When your access token expires, use the refresh_token tool to get a new one. For subsequent Gmail operations, include the access token with each request.

The server handles token refreshing automatically when needed, making it easy to maintain continuous access to Gmail without managing authentication flows manually.

Security Considerations

Since credentials are passed with each request and not stored on the server, this implementation provides good separation of concerns. However, ensure your MCP client securely stores these credentials and transmits them securely to the server.