Overview

This MCP (Model Context Protocol) server exposes Gmail access to remote agents and services without requiring local credential files or manual file-system setup. The server runs a headless browser to interact with Gmail’s web interface and translates common mail actions (send, read, search, download attachments) into MCP tools that LLMs or microservices can call over HTTP. That makes it easy to integrate Gmail into automated workflows and chat agents while keeping credentials out of the repository and avoiding local OAuth file handling.

The implementation is intended for hosted or ephemeral environments: credentials are supplied at runtime (for example via environment variables or container secrets), and the server manages an in-memory or ephemeral browser session. This lets developers deploy a lightweight Gmail bridge for agents that need to read or compose messages without embedding Gmail tokens in the application filesystem.

Features

Send and compose Gmail messages programmatically via MCP tools
Fetch, search and summarize inbox or thread contents
Download attachments and expose them through MCP files-storage (streaming)
Headless-browser based authentication — no local credential files required
Simple HTTP/MCP interface so LLMs and agents can call mail operations
Container-friendly configuration for cloud deployment

Installation / Configuration

Minimum steps to get the server running locally or in a container. The repository is Node-based and expects Node.js >= 16.

Clone and run locally:

git clone https://github.com/baryhuang/mcp-headless-gmail.git
cd mcp-headless-gmail
npm install
# Set required environment variables before starting
export GOOGLE_EMAIL="[email protected]"
export GOOGLE_PASSWORD="your-password-or-app-password"
export MCP_PORT=3000
export MCP_SECRET="a-secret-to-authenticate-mcp-clients"
npm start

Run with Docker (example):

# build (if a Dockerfile is provided)
docker build -t mcp-headless-gmail .

# run with environment variables or use your container secret mechanism
docker run -d \
  -e GOOGLE_EMAIL="[email protected]" \
  -e GOOGLE_PASSWORD="your-password-or-app-password" \
  -e MCP_PORT=3000 \
  -e MCP_SECRET="a-secret" \
  -p 3000:3000 \
  --name mcp-gmail \
  mcp-headless-gmail

Environment variables to set:

GOOGLE_EMAIL — Gmail address to sign in with
GOOGLE_PASSWORD — password or app-specific password (recommended when 2FA is enabled)
MCP_PORT — port the MCP server listens on (default 3000)
MCP_SECRET — shared secret for client-tool authentication (optional but recommended)

Security note: prefer using app-specific passwords or OAuth where appropriate, and use container secret storage / cloud secret managers to inject credentials.

Available Tools / Resources

The server exposes a set of MCP tools that map to Gmail workflows. Tool names and signatures are presented in the table below (names are representative; check the running server’s tool registry for exact names).

Tool name (example)	Purpose	Input (JSON)	Output
gmail.send	Send a message	{ to, cc?, bcc?, subject, body, html? }	{ messageId, threadId, status }
gmail.fetchThread	Fetch a thread by ID	{ threadId }	{ messages: […] }
gmail.search	Search messages	{ query, maxResults? }	{ results: [ { id, snippet, subject, from, date } ] }
gmail.downloadAttachment	Stream an attachment	{ messageId, attachmentId }	file stream (via MCP files-storage or URL)

How agents discover tools:

The MCP server exposes a tool registry endpoint. Agents should authenticate with MCP_SECRET (if enabled) and call the tool by name with a JSON payload. Attachments are made available via the server’s files-storage integration so large binaries can be transferred efficiently.

Example curl (send):

curl -X POST "http://localhost:3000/tools/gmail.send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${MCP_SECRET}" \
  -d '{
    "to": "[email protected]",
    "subject": "Hello from MCP",
    "body": "This message was sent by an MCP-connected agent."
  }'

Use Cases

Programmatic outbound messages: an LLM agent composes and sends confirmation emails after processing user requests (orders, reservations) without needing the user to upload Gmail credentials to the agent host.
Inbox summarization for agents: periodically fetch unread messages matching a query (e.g., receipts, shipping updates), summarize them, and notify a downstream system or user.
Receipt and invoice extraction: search for messages from specific senders, download and scan attachments (PDFs/images) using your document-processing pipeline. Attachments are exposed via the MCP files-storage endpoint for downstream processing.
Remote-assisted troubleshooting: allow an ops assistant or trusted LLM to read specific

Gmail Headless MCP Server No Local Credentials

Overview

Features

Installation / Configuration

Available Tools / Resources

Use Cases