You can run the Gmail MCP Server to interact with your inbox through natural language, receive categorized daily summaries, and connect to Home Assistant. It runs with Docker for easy deployment and provides a REST API you can query from MCP clients or Home Assistant REST sensors.

How to use

Connect to the Gmail MCP Server from any MCP client to start querying your inbox, generate daily category summaries, and trigger Home Assistant integrations. You can use Claude Desktop or Home Assistant via the SSE transport, or interact directly through the REST API at the server’s endpoints. Practical uses include performing natural language searches, viewing unread counts by category, and routing daily summaries to Home Assistant as text or via a webhook.

How to install

Prerequisites you need before installing are Docker, Docker Compose, and (optionally) Python for local development commands. Ensure Docker Engine is running on your machine.

1. Prepare the Gmail MCP Server files and environment.

Navigate to your working directory where the Gmail MCP files reside

cd mcp_gmail

Copy the example environment file and edit it with your credentials

cp .env.example .env

Open the .env file and set your Google credentials (CLIENT_ID/CLIENT_SECRET) as shown

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com

GOOGLE_CLIENT_SECRET=your-client-secret

2. Authenticate and initialize using Docker Compose.

docker compose --profile setup run --rm gmail-mcp-auth

This step will open a browser window to authenticate with Google and save the OAuth token to ./credentials/token.json.

3. Start the Gmail MCP Server with Docker Compose.

docker compose up -d

4. Verify the server is running and view logs if needed.

docker compose logs -f gmail-mcp

The REST API for the Gmail MCP Server will be available at http://localhost:8000.

Additional installation and development paths

If you prefer running locally without Docker, you can use the MCP development commands. You may run authentication, API, and the MCP server directly in sequence.

# Authenticate (local flow)
mcp-gmail-auth

# Start the API server (local development)
mcp-gmail-api

# Run the MCP server (stdio)
mcp-gmail

Available tools

gmail_search

Search emails with a query and optional filters using natural language or Gmail syntax.

gmail_get_email

Retrieve full content of an email by its ID.

gmail_list_unread

List unread emails with optional category filtering.

gmail_daily_summary

Generate a categorized daily summary of emails.

gmail_category_summary

Provide a summary for a specific category.

gmail_inbox_stats

Return current inbox statistics such as unread counts.

gmail_list_labels

List all Gmail labels configured for the account.

gmail_create_label

Create a new Gmail label.

gmail_delete_label

Delete a Gmail label.

gmail_get_categories

Show the configured email categories.

gmail_mark_as_read_by_ids

Mark specified emails as read by their IDs.

gmail_mark_as_read_by_query

Mark emails matching a query as read.

gmail_send_email

Send an email (plain text or HTML).

gmail_add_labels_to_messages

Add labels to specified messages.

gmail_remove_labels_from_messages

Remove labels from specified messages.