gmail-fast-mcp

Gmail MCP server built with FastMCP. Provides 19 tools for email operations, label management, filter management, and attachment handling via the Gmail API.

Setup

1. Google OAuth Credentials

Place your Google Cloud OAuth client credentials at ~/.gmail-mcp/gcp-oauth.keys.json (or in the project directory — they'll be copied automatically).

2. Authenticate

uv run python -m gmail_fast_mcp auth

This opens a browser for the OAuth flow and saves tokens to ~/.gmail-mcp/credentials.json.

For cloud environments with a custom callback URL:

uv run python -m gmail_fast_mcp auth https://your-domain.com/oauth2callback

3. Run the Server

uv run python -m gmail_fast_mcp

MCP Client Configuration

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gmail-fast-mcp", "python", "-m", "gmail_fast_mcp"]
    }
  }
}

Tools

Tool	Description
send_email	Send an email (text/html/multipart, attachments, threading)
draft_email	Create an email draft
read_email	Retrieve email content and attachment metadata
search_emails	Search using Gmail query syntax
modify_email	Add/remove labels on a message
trash_email	Move a message to trash
batch_modify_emails	Modify labels on multiple messages
batch_trash_emails	Trash multiple messages
list_email_labels	List all Gmail labels
create_label	Create a new label
update_label	Update label name/visibility
delete_label	Delete a user label
get_or_create_label	Find existing label or create it
create_filter	Create a filter with custom criteria/actions
list_filters	List all filters
get_filter	Get filter details
delete_filter	Delete a filter
create_filter_from_template	Create a filter from a preset template
download_attachment	Download an attachment to disk

Gmail API Scopes

• gmail.modify — Read, send, modify emails and labels
• gmail.settings.basic — Manage filters and settings