Gmail

You can run a Gmail MCP Server locally to let Claude interact with your Gmail account through natural language. This server exposes a rich set of email management capabilities, from sending and reading messages to organizing labels and drafts, all authenticated securely with OAuth. Run it on your machine and connect it to Claude Desktop or other MCP clients to enable conversational email workflows without exposing your data to external services.

How to use

Start the Gmail MCP Server on your machine using Python. It runs locally and communicates with your MCP client through a standard transport. You can run it in normal mode or in SSE mode for HTTP-based injection. Once running, you connect your MCP client (for example Claude Desktop) to the server using the provided MCP configuration. From there you can ask your AI to compose emails, fetch unread messages, search your inbox, manage labels, automate drafts, and perform batch operations — all through natural language prompts.

How to install

Prerequisites: Install Python 3.8 or higher on your machine. Ensure you have a Google Cloud project with the Gmail API enabled and OAuth credentials prepared.

Step 1. Install Python dependencies

pip install -r requirements.txt

Step 2. Prepare Google Cloud OAuth credentials
- Create a Google Cloud project and enable the Gmail API
- Set up OAuth consent screen
- Create OAuth Client ID credentials (Desktop application)
- Download credentials.json to the project root

Step 3. Prepare your local environment for running the server
You will run the server script directly from its location using Python. The server can also be started with an SSE mode flag for HTTP transport if desired.

## Set up Google Cloud and OAuth credentials

Create a Google Cloud project, enable Gmail API, configure OAuth consent, and download credentials as credentials.json. Place credentials.json in the project root so the server can authenticate and obtain access tokens during the first run.

## First Run and Authentication

Run the server once to trigger the OAuth flow in your browser and authorize access to your Gmail account. This initial run creates a token.json file in the project directory, which is reused for subsequent runs without re-authenticating.

## Configure Claude Desktop

Add the Gmail MCP server to Claude Desktop’s configuration so Claude can reach it via MCP. Use an absolute path to the Gmail MCP server script when you specify the command and arguments.

{ "mcpServers": { "gmail": { "command": "python", "args": [ "/absolute/path/to/gmail-mcp-server/gmail_server.py" ] } } }

## Notes on running modes

You can run the Gmail MCP Server in normal mode or in SSE mode. For SSE, start the server with the --sse flag to expose an HTTP-based transport on a chosen port.

python gmail_server.py --sse 3000

## Available tools

### send\_email

Send basic emails with text or HTML content, optionally including attachments.

### send\_email\_with\_attachment

Send emails with a single file attachment.

### send\_email\_with\_multiple\_attachments

Send emails with multiple attachments.

### read\_email

Read the content of a specific email by its ID with proper parsing of the message.

### get\_unread\_emails

Retrieve a list of unread emails from your inbox.

### get\_important\_emails

Fetch emails marked as important.

### get\_emails\_with\_attachments

List emails that contain attachments.

### get\_recent\_emails

Get emails from the last N days.

### search\_emails

Search emails using Gmail’s query syntax.

### get\_email\_labels

List all Gmail labels or folders.

### create\_email\_label

Create a new label in Gmail.

### delete\_email\_label

Delete an existing label.

### label\_email

Apply a label to a specific email.

### remove\_email\_label

Remove a label from an email.

### mark\_as\_read

Mark an email as read.

### mark\_as\_unread

Mark an email as unread.

### delete\_email

Move an email to the trash.

### create\_email\_draft

Create a new draft email.

### update\_email\_draft

Update an existing draft.

### list\_email\_drafts

List available drafts.

### send\_draft

Send an existing draft email.

### batch\_apply\_label

Apply a label to multiple emails in a single operation.

### batch\_delete\_emails

Move multiple emails to trash in one action.

### get\_email\_profile

Retrieve Gmail profile information.

### summarize\_recent\_emails

Create a summary of recent emails.