Gmail MCP Server
About
A single-file MCP-server for interacting with Gmail. Works with Claude Desktop and Cursor.
Details
- License
- MIT
Explore
- Search Gmail threads using standard Gmail search queries
- Create and update email drafts with thread awareness
- Extract text from PDF, DOCX, and TXT attachments safely
- Generate an email style guide from your last 25 sent emails
- Persistent HTTP mode to avoid OAuth popup spam
The difference: You start the server manually once instead of letting Cursor start it fresh each time.
You can edit these config files directly if you know where to find them:
- Cursor: C:\Users\[User]\.cursor\mcp.json
- Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows)
If you want to run this MCP server outside of an agent, you can create a .env file based on the .env.example file and supply the environment variables that way, or export them into your environment prior to running:
export GMAIL_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
export GMAIL_CLIENT_SECRET=your_client_secret_here
export OPENAI_API_KEY=your_openai_api_key_here
``
- Use
/server-status in your MCP client to see exact file paths
- Delete token.json` to force re-authentication with updated permissionssearch_threads
Search Gmail with queries like "from:[email protected]" or "subject:meeting" (includes draft info)
create_draft
Create email drafts or update existing drafts (AI will request style guide first)
extract_attachment_by_filename
Safely extract text from PDF, DOCX, and TXT attachments using filename
get_personal_email_style_guide
Get your email writing style guide (this is a temporary tool, created because most agents do not yet support fetching resources--once agents implement MCP resources better, then thsi tool can be removed)
Tools:
- search_threads - Search Gmail with queries like "from:[email protected]" or "subject:meeting" (includes draft info)
- create_draft - Create email drafts or update existing drafts (AI will request style guide first)
- extract_attachment_by_filename - Safely extract text from PDF, DOCX, and TXT attachments using filename
- get_personal_email_style_guide - Get your email writing style guide (this is a temporary tool, created because most agents do not yet support fetching resources--once agents implement MCP resources better, then thsi tool can be removed)
Resources:
- file://personal-email-style-guide - Your personal email writing style (auto-generated or manual)
Prompts:
- /generate-email-tone - Analyze your sent emails to create personalized writing style
- /server-status - Show file locations and server status
An MCP server that lets AI agents search Gmail threads, understand your email writing style, and create draft emails.
1. Get Google Authentication
Step 1: Create a Google Cloud Project
1. Go to Google Cloud Console 2. Click "Select a project" dropdown at the top 3. Click "New Project" 4. Enter a project name (e.g., "Gmail MCP Server") 5. Click "Create"Step 2: Enable Gmail API
1. In your new project, go to "APIs & Services" → "Library" 2. Search for "Gmail API" 3. Click on "Gmail API" and click "Enable"Step 3: Create OAuth2 Credentials
1. Go to "APIs & Services" → "Credentials" 2. Click "Create Credentials" → "OAuth Client ID" 3. If prompted, configure the OAuth consent screen: - Choose "External" user type - Fill in required fields (App name, User support email, Developer email) - Add your email to "Test users" section - Save and continue through all steps 4. Back in Credentials, click "Create Credentials" → "OAuth Client ID" 5. Choose "Desktop application" as the application type 6. Enter a name (e.g., "Gmail MCP Client") 7. Click "Create" 8. Important: Copy the Client ID and Client Secret from the confirmation dialog (you'll need these for configuration)Step 4: Grant OAuth Scopes
When you first run the server, it will open your browser for authorization. The server requests only these minimal permissions:What We Request:
- ✅ Gmail Readonly Access (gmail.readonly)
- Search and read your email messages
- Download email attachments
- View email metadata (subjects, senders, dates)
- ✅ Gmail Compose Access (gmail.compose)
- Create email drafts
- Update existing drafts
- Delete drafts
- Send emails (permission granted but not used by this server)
What This Server Actualy Implements:
- ✅ Search and read emails - Full search capabilities - ✅ Extract attachment text - Safe PDF/DOCX/TXT text extraction - ✅ Create/update drafts - Smart draft management with thread awareness - ❌ Send emails - Server doesn't implement sending (though permission is granted) - ❌ Delete emails - Server doesn't implement deletion - ❌ Modify labels - Server doesn't implement label management2. Add to MCP Clients
Build the server first: go build .
You'll want to add this to your agent's configuration file:
{
"mcpServers": {
"gmail": {
"command": "C:/path/to/your/auto-gmail.exe",
"env": {
"GMAIL_CLIENT_ID": "your_client_id_here.apps.googleusercontent.com",
"GMAIL_CLIENT_SECRET": "your_client_secret_here",
"OPENAI_API_KEY": "your_openai_api_key_here"
}
}
}
}
⚡ Persistent HTTP Mode (Recommended to Avoid OAuth Popups)
Problem: In stdio mode, Cursor starts a fresh server process each time (and for each tab), causing OAuth popup spam.
Solution: Run the server as a persistent HTTP daemon that authenticates once and stays running.
Quick Start:
```bashSign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
