The Gmail AutoAuth MCP server integrates Gmail functionality into Claude Desktop through Model Context Protocol, enabling AI assistants to manage emails with natural language commands. It supports sending emails with attachments, downloading attachments, searching emails, managing labels, and performing batch operations.
For automatic installation through Smithery:
npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude
http://localhost:3000/oauth2callback to authorized redirect URIsgcp-oauth.keys.jsonGlobal Authentication (Recommended):
# First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/
# Run authentication from anywhere
npx @gongrzhe/server-gmail-autoauth-mcp auth
Local Authentication:
# Place gcp-oauth.keys.json in your current directory
npx @gongrzhe/server-gmail-autoauth-mcp auth
The authentication process will:
~/.gmail-mcp/~/.gmail-mcp/credentials.jsonAdd this to your Claude Desktop configuration:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}
For Docker users:
docker run -i --rm \
--mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
-v mcp-gmail:/gmail-server \
-e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
-e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
-p 3000:3000 \
mcp/gmail auth
{
"mcpServers": {
"gmail": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"mcp-gmail:/gmail-server",
"-e",
"GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
"mcp/gmail"
]
}
}
}
For cloud environments:
npx @gongrzhe/server-gmail-autoauth-mcp auth https://your-domain.com/oauth2callback
Setup instructions:
Sends a new email immediately with various format options.
Basic email:
{
"to": ["[email protected]"],
"subject": "Meeting Tomorrow",
"body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
"cc": ["[email protected]"],
"bcc": ["[email protected]"],
"mimeType": "text/plain"
}
Email with attachments:
{
"to": ["[email protected]"],
"subject": "Project Files",
"body": "Hi,\n\nPlease find the project files attached.\n\nBest regards",
"attachments": [
"/path/to/document.pdf",
"/path/to/spreadsheet.xlsx"
]
}
HTML email:
{
"to": ["[email protected]"],
"subject": "Meeting Tomorrow",
"mimeType": "text/html",
"body": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p></body></html>"
}
Creates a draft without sending:
{
"to": ["[email protected]"],
"subject": "Draft Report",
"body": "Here's the draft report for your review.",
"cc": ["[email protected]"],
"attachments": ["/path/to/draft_report.docx"]
}
Retrieves email content by ID:
{
"messageId": "182ab45cd67ef"
}
Response includes attachment details:
Subject: Project Files
From: [email protected]
To: [email protected]
Date: Thu, 19 Jun 2025 10:30:00 -0400
Email body content here...
Attachments (2):
- document.pdf (application/pdf, 245 KB, ID: ANGjdJ9fkTs-i3GCQo5o97f_itG...)
- spreadsheet.xlsx (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, 89 KB, ID: BWHkeL8gkUt-j4HDRp6o98g_juI...)
Downloads email attachments to your local filesystem:
{
"messageId": "182ab45cd67ef",
"attachmentId": "ANGjdJ9fkTs-i3GCQo5o97f_itG...",
"savePath": "/path/to/downloads",
"filename": "downloaded_document.pdf"
}
Searches for emails using Gmail search syntax:
{
"query": "from:[email protected] after:2024/01/01 has:attachment",
"maxResults": 10
}
Adds or removes labels from emails:
{
"messageId": "182ab45cd67ef",
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"]
}
Permanently deletes an email:
{
"messageId": "182ab45cd67ef"
}
Retrieves all available Gmail labels:
{}
Creates a new Gmail label:
{
"name": "Important Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
Updates an existing Gmail label:
{
"id": "Label_1234567890",
"name": "Urgent Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
Deletes a Gmail label:
{
"id": "Label_1234567890"
}
Gets a label or creates it if it doesn't exist:
{
"name": "Project XYZ",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
Modifies labels for multiple emails:
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"],
"batchSize": 50
}
Permanently deletes multiple emails:
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"batchSize": 50
}
The search_emails tool supports Gmail's search operators:
| Operator | Example | Description |
|---|---|---|
from: |
from:[email protected] |
Emails from a specific sender |
to: |
to:[email protected] |
Emails sent to a specific recipient |
subject: |
subject:"meeting notes" |
Emails with specific text in the subject |
has:attachment |
has:attachment |
Emails with attachments |
after: |
after:2024/01/01 |
Emails received after a date |
before: |
before:2024/02/01 |
Emails received before a date |
is: |
is:unread |
Emails with a specific state |
label: |
label:work |
Emails with a specific label |
You can combine multiple operators: from:[email protected] after:2024/01/01 has:attachment
gcp-oauth.keys.json is in your current directory or ~/.gmail-mcp/web or installed credentialsTo add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "gmail" '{"command":"npx","args":["@gongrzhe/server-gmail-autoauth-mcp"]}'See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add this to your configuration file:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}3. Restart Claude Desktop for the changes to take effect