Gmail MCP Server

A local MCP server that connects Claude Code to your Gmail account for reading, searching, drafting, and managing emails.

Required OAuth Scopes

Scope	Purpose
gmail.readonly	Read emails and search inbox
gmail.compose	Create drafts
gmail.modify	Modify labels, mark read/unread
gmail.settings.basic	Read and create filters

Features

• Read & Search: List emails, search with Gmail's powerful query syntax
• Draft Responses: Create drafts that open directly in Gmail for editing/sending
• Label Management: List, create, and apply labels to messages
• Filter Management: Create filters to automatically organize incoming mail
• Smart Workflows: Find priority emails, identify newsletters, daily summaries

Installation

1. Clone and Build

cd ~/Projects/emailbot  # or wherever you cloned this
npm install
npm run build

2. Set Up Google Cloud Credentials

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable the Gmail API:
   • Search for "Gmail API" and click Enable
4. Configure OAuth consent screen:
   • Choose "External" user type
   • Fill in app name (e.g., "Gmail MCP") and your email
   • Add your email as a test user
5. Create OAuth 2.0 credentials:
   • Go to Credentials → Create Credentials → OAuth 2.0 Client ID
   • Choose "Desktop application"
   • Download the JSON file
6. Save as ~/.gmail-mcp/credentials.json

Or run the setup wizard:

npm run setup

3. Add to Claude Code

Add to your Claude Code MCP configuration:

claude mcp add --transport stdio gmail -- node /path/to/emailbot/build/index.js

Or add manually to ~/.claude/settings.local.json:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/emailbot/build/index.js"]
    }
  }
}

4. Authenticate

In Claude Code, run:

Use gmail_auth_status to check authentication

Follow the prompts to complete OAuth.

Available Tools

Authentication

• gmail_auth_status - Check auth status, get setup instructions
• gmail_authenticate - Start OAuth flow
• gmail_complete_auth - Complete OAuth with code

Email Reading

• gmail_list_emails - List recent emails with optional query
• gmail_get_email - Get full email content by ID
• gmail_search - Search with Gmail query syntax

Drafts

• gmail_create_draft - Create draft (returns Gmail link)
• gmail_list_drafts - List current drafts

Labels

• gmail_list_labels - List all labels with counts
• gmail_create_label - Create new label
• gmail_modify_labels - Add/remove labels from emails

Filters

• gmail_list_filters - List all filters
• gmail_create_filter - Create auto-filter
• gmail_delete_filter - Delete filter

Utilities

• gmail_mark_read - Mark email as read
• gmail_mark_unread - Mark email as unread

Smart Workflows

• gmail_get_priority_emails - Get emails needing response
• gmail_find_newsletters - Find newsletter senders
• gmail_find_unsubscribe_candidates - Find unsubscribe opportunities
• gmail_daily_summary - Daily inbox summary

Example Workflows

Get Priority Emails to Respond To

Show me priority emails I need to respond to

Draft a Response

Read email ID abc123 and draft a response accepting their meeting request

Set Up Newsletter Filter

Find newsletters in my inbox, then create a filter for [sender]
that adds the "Newsletter" label and marks as read

Daily Summary

Give me my daily email summary

Gmail Search Syntax

The server supports Gmail's full search syntax:

• is:unread - Unread emails
• from:sender@example.com - From specific sender
• to:me - Sent directly to you
• subject:keyword - Subject contains keyword
• has:attachment - Has attachments
• older_than:7d - Older than 7 days
• newer_than:1d - From last 24 hours
• -category:promotions - Exclude promotions

Security Notes

• Credentials stored in ~/.gmail-mcp/credentials.json
• OAuth tokens stored in ~/.gmail-mcp/token.json
• Never commit these files to git
• Server only creates drafts, never sends automatically
• All sends require manual action in Gmail UI

Troubleshooting

"Not authenticated" errors

Run gmail_auth_status and follow setup instructions.

OAuth callback fails

Make sure no other process is using port 3000.

Token expired

Delete ~/.gmail-mcp/token.json and re-authenticate.

License

MIT