Gmail AutoAuth MCP Server allows AI assistants to manage Gmail through natural language interactions. It provides comprehensive email and label management capabilities through the Model Context Protocol (MCP) framework.
To install Gmail AutoAuth for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude
Create a Google Cloud Project and obtain credentials:
a. Create a Google Cloud Project:
b. Create OAuth 2.0 Credentials:
http://localhost:3000/oauth2callback to the authorized redirect URIsgcp-oauth.keys.jsonRun Authentication:
You can authenticate in two ways:
a. Global 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
b. Local Authentication:
# Place gcp-oauth.keys.json in your current directory
# The file will be automatically copied to global config
npx @gongrzhe/server-gmail-autoauth-mcp auth
Configure in Claude Desktop:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}
If you prefer using Docker:
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 server environments (like n8n), you can specify a custom callback URL:
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
Configure Reverse Proxy:
DNS Configuration:
Google Cloud Platform Setup:
Run Authentication:
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
send_email)Sends a new email immediately. Supports plain text, HTML, or multipart emails.
{
"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"
}
HTML Email Example:
{
"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><p>Best regards</p></body></html>"
}
Multipart Email Example:
{
"to": ["[email protected]"],
"subject": "Meeting Tomorrow",
"mimeType": "multipart/alternative",
"body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
"htmlBody": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}
draft_email)Creates a draft email without sending it.
{
"to": ["[email protected]"],
"subject": "Draft Report",
"body": "Here's the draft report for your review.",
"cc": ["[email protected]"]
}
read_email)Retrieves the content of a specific email by its ID.
{
"messageId": "182ab45cd67ef"
}
search_emails)Searches for emails using Gmail search syntax.
{
"query": "from:[email protected] after:2024/01/01 has:attachment",
"maxResults": 10
}
modify_email)Adds or removes labels from emails (move to different folders, archive, etc.).
{
"messageId": "182ab45cd67ef",
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"]
}
delete_email)Permanently deletes an email.
{
"messageId": "182ab45cd67ef"
}
list_email_labels)Retrieves all available Gmail labels.
{}
create_label)Creates a new Gmail label.
{
"name": "Important Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
update_label)Updates an existing Gmail label.
{
"id": "Label_1234567890",
"name": "Urgent Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
delete_label)Deletes a Gmail label.
{
"id": "Label_1234567890"
}
get_or_create_label)Gets an existing label by name or creates it if it doesn't exist.
{
"name": "Project XYZ",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
batch_modify_emails)Modifies labels for multiple emails in efficient batches.
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"],
"batchSize": 50
}
batch_delete_emails)Permanently deletes multiple emails in efficient batches.
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"batchSize": 50
}
The search_emails tool supports Gmail's powerful 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
The server intelligently extracts email content from complex MIME structures:
The server fully supports non-ASCII characters in email subjects and content, including:
The server provides a complete set of tools for managing Gmail labels:
Label visibility settings include:
messageListVisibility: Controls whether the label appears in the message list (show or hide)labelListVisibility: Controls how the label appears in the label list (labelShow, labelShowIfUnread, or labelHide)The server includes efficient batch processing capabilities:
OAuth Keys Not Found
gcp-oauth.keys.json is in either your current directory or ~/.gmail-mcp/Invalid Credentials Format
web or installed credentialsPort Already in Use
Batch Operation Failures
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 > MCP and click "Add new global MCP server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"cursor-rules-mcp": {
"command": "npx",
"args": [
"-y",
"cursor-rules-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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.