home / mcp / gmail mcp server

Gmail MCP Server

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

Installation

Add the following to your MCP client configuration file.

Configuration

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

You run an MCP server that enables headless Gmail access, allowing you to fetch recent emails, retrieve full email bodies in chunks, send emails, and refresh tokens without storing credentials locally. This keeps credential handling separated from server logic while enabling remote, containerized operation.

How to use

You interact with the server through an MCP client. The available capabilities include fetching recent emails, retrieving full email content in offset-based chunks, sending emails, and refreshing access tokens as needed. Tokens can be managed externally or via a dedicated refresh path, while the server handles Gmail API calls using the provided tokens.

How to install

Prerequisites: you need Python 3.10 or higher and Google API credentials (client ID, client secret, access token, and refresh token). You also can run the server via Docker or install locally for development.

Install locally (Python) after cloning the project and navigating into the directory.

# Create and activate a virtual environment (optional but recommended)
python3 -m venv .venv
source .venv/bin/activate

# Install the MCP Gmail server locally in editable mode
pip install -e .

Additional sections

Configuration and runtime are designed to work with a compatible MCP client. If you choose to run the server in Docker, you can start a container with the standard image name used for this MCP server.

Security note: keep your Google API credentials secure. Do not expose your access or refresh tokens in client calls or logs. The server relies on tokens supplied by the client, and automatic token refreshing is supported.

Examples of common usage patterns include refreshing tokens when needed, fetching a small set of recent messages, and streaming the full body content in chunks by offset. When retrieving large bodies, issue successive requests with increasing offsets until the entire content is obtained.

Troubleshooting tips: verify token validity, ensure Gmail API scopes cover read and send actions, and confirm network access from the host running the MCP server to Google services.

Available tools

get_recent_emails

Fetch the most recent Gmail messages, returning metadata and the first 1k characters of each email body.

get_email_body_chunk

Retrieve the full email body in 1k-character chunks by providing an offset or a thread ID, enabling streaming of long messages.

send_email

Send an email via Gmail using the server, specifying recipient, subject, and body or html_body.

refresh_token

Refresh the Google access token using the refresh token, client ID, and client secret so subsequent calls remain authorized.