Submit
domdomegg

gmail-mcp

Community domdomegg
Updated

📧 MCP server for Gmail

gmail-mcp

MCP server for Gmail - read, send, archive, and manage emails.

Setup

1. Create Google OAuth credentials

  1. Go to Google Cloud Console
  2. Create a new project (or use existing)
  3. Enable the Gmail API
  4. Go to APIs & Services → OAuth consent screen, set up consent screen
  5. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
  6. Choose Web application
  7. Add http://localhost:3000/callback to Authorized redirect URIs
  8. Note your Client ID and Client Secret

2. Run the server

GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start

The server runs on http://localhost:3000 by default. Change with PORT=3001.

3. Add to your MCP client

claude mcp add gmail-mcp http://localhost:3000/mcp

Architecture

This server acts as an OAuth proxy to Google:

graph LR
    A[MCP client] <--> B[gmail-mcp] <--> C[Google OAuth/API]
  1. Server advertises itself as an OAuth authorization server via /.well-known/oauth-authorization-server
  2. /register returns the Google OAuth client credentials
  3. /authorize redirects to Google, encoding the client's callback URL in state
  4. /callback receives the code from Google and forwards to the client's callback
  5. /token proxies token requests to Google, injecting client credentials
  6. /mcp handles MCP requests, using the bearer token to call Gmail API

The server holds no tokens or state - it just proxies OAuth to Google.

Tools

Tool Description
gmail_get_profile Get user's email address and profile info
Messages
gmail_messages_list Search/list messages (consider gmail_threads_list instead)
gmail_message_get Get a single message
gmail_message_send Send an email
gmail_message_modify Add/remove labels
gmail_message_archive Archive (remove from inbox)
gmail_message_trash Move to trash
gmail_message_untrash Restore from trash
gmail_message_delete Permanently delete
gmail_messages_batch_modify Bulk label changes
gmail_messages_batch_delete Bulk permanent delete
Threads
gmail_threads_list Search/list threads (recommended)
gmail_thread_get Get all messages in a thread (recommended)
gmail_thread_modify Add/remove labels
gmail_thread_trash Move to trash
gmail_thread_untrash Restore from trash
gmail_thread_delete Permanently delete
Drafts
gmail_drafts_list List drafts
gmail_draft_get Get a draft
gmail_draft_create Create a draft
gmail_draft_update Update a draft
gmail_draft_send Send a draft
gmail_draft_delete Delete a draft
Labels
gmail_labels_list List all labels
gmail_label_get Get a label
gmail_label_create Create a label
gmail_label_update Update a label
gmail_label_delete Delete a label
Attachments
gmail_attachment_get Download attachment
Filters
gmail_filters_list List email filters
gmail_filter_get Get a filter
gmail_filter_create Create a filter
gmail_filter_delete Delete a filter
Settings
gmail_vacation_get Get vacation auto-reply settings
gmail_vacation_set Set vacation auto-reply settings

Gmail API Scopes

  • gmail.readonly - Read messages and labels
  • gmail.send - Send messages
  • gmail.modify - Modify messages (archive, labels, trash)

Development

npm install
npm run build
npm run lint
npm test

MCP Server · Populars

MCP Server · New