Gmail MCP Server

A Model Context Protocol (MCP) server that provides Gmail access for Claude Code and other MCP clients. Built with FastMCP.

Features

• list_unread - List unread emails from inbox
• search - Search emails using Gmail query syntax
• archive - Archive emails (removes from inbox)
• mark_as_read - Mark emails as read without archiving
• get_labels - Get all Gmail labels

Installation

No local installation required! Run directly from GitHub using uvx:

uvx --from git+https://github.com/fred-drake/gmail-mcp gmail-mcp

Setup

1. Create Google Cloud OAuth Credentials

1. Go to Google Cloud Console

2. Create a new project or select an existing one:

   • Click the project dropdown at the top of the page
   • Click "New Project", give it a name, and create it
   • Make sure your new project is selected

3. Enable the Gmail API:

   • Navigate to "APIs & Services" > "Library"
   • Search for "Gmail API" and click on it
   • Click "Enable"

4. Configure the OAuth consent screen (required before creating credentials):

   • Go to "APIs & Services" > "OAuth consent screen"
   • Select "External" as the user type and click "Create"
   • Fill in the required fields:
     • App name: Choose any name (e.g., "Gmail MCP")
     • User support email: Select your email
     • Developer contact email: Enter your email
   • Click "Save and Continue"
   • On the "Scopes" page, click "Save and Continue" (no changes needed)
   • On the "Test users" page:
     • Click "Add Users"
     • Enter the Gmail address you want to access (this is critical!)
     • Click "Add" then "Save and Continue"
   • Click "Back to Dashboard"

5. Create OAuth credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Desktop app" as the application type
   • Give it a name (e.g., "Gmail MCP Desktop")
   • Click "Create"
   • Click "Download JSON" to save the credentials file
   • Store this file securely - you'll need the path for configuration

2. Set Environment Variables

Set the path to your OAuth credentials file:

export GMAIL_MCP_CREDENTIALS_PATH="/path/to/your/credentials.json"

Optionally, customize the token cache location (default: ~/.config/gmail-mcp/token.json):

export GMAIL_MCP_TOKEN_PATH="/custom/path/token.json"

3. Run OAuth Setup

Run the interactive setup to authenticate:

uvx --from git+https://github.com/fred-drake/gmail-mcp gmail-mcp --setup

This will open a browser window for Google OAuth authentication. After authorizing, the token will be cached for future use.

MCP Client Configuration

Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fred-drake/gmail-mcp", "gmail-mcp"],
      "env": {
        "GMAIL_MCP_CREDENTIALS_PATH": "/path/to/your/credentials.json"
      }
    }
  }
}

With Custom Token Path

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fred-drake/gmail-mcp", "gmail-mcp"],
      "env": {
        "GMAIL_MCP_CREDENTIALS_PATH": "/path/to/your/credentials.json",
        "GMAIL_MCP_TOKEN_PATH": "/custom/path/token.json"
      }
    }
  }
}

Environment Variables

Variable	Required	Default	Description
GMAIL_MCP_CREDENTIALS_PATH	Yes	-	Path to OAuth credentials JSON
GMAIL_MCP_TOKEN_PATH	No	~/.config/gmail-mcp/token.json	Path to token cache file

Tool Reference

list_unread

List unread emails from inbox.

Parameters:

• max_results (int, optional): Maximum emails to return (1-100). Default: 20.

Returns: List of email objects with id, from, subject, date, snippet, labels, body_preview.

search

Search emails using Gmail query syntax.

Parameters:

• query (str): Gmail search query (e.g., "from:user@example.com is:unread")
• max_results (int, optional): Maximum results (1-100). Default: 20.

Returns: List of matching email objects.

Example queries:

• from:notifications@github.com - Emails from GitHub
• is:unread newer_than:1d - Unread emails from last 24 hours
• subject:invoice - Emails with "invoice" in subject
• has:attachment larger:5M - Emails with attachments over 5MB

archive

Archive emails by removing INBOX and UNREAD labels.

Parameters:

• message_ids (list[str]): List of message IDs to archive.

Returns: Dict with archived_count, failed_count, and details.

mark_as_read

Mark emails as read without archiving.

Parameters:

• message_ids (list[str]): List of message IDs to mark as read.

Returns: Dict with marked_count, failed_count, and details.

get_labels

Get all Gmail labels for the authenticated user.

Returns: List of label objects with id, name, type, and message counts.

Development

Prerequisites

• Python 3.13+
• Nix (optional, for reproducible environment)

Setup with Nix

cd gmail-mcp
nix develop

Setup with pip

cd gmail-mcp
pip install -e ".[dev]"

Running Tests

pytest

Linting

ruff check .
ruff format .

License

MIT