gmail-mcp
MCP server for Gmail - read, send, archive, and manage emails.
Use Cases
Flight check-in: "Check me in for my flight tomorrow" → finds your confirmation email, extracts the booking reference, and completes check-in with browser use.
Expense submission: "Submit my Amazon purchases from last week as expenses" → finds receipts, extracts amounts/categories, and files them in your expense system.
Package tracking: "Where's my package from Acme?" → finds the shipping notification, extracts the tracking number, and fetches current delivery status.
Find that attachment: "What did we settle on for the budget? Michelle sent me something yesterday" → locates the email and opens the attached spreadsheet.
Vacation mode: "I'm on holiday Dec 20-Jan 2" → sets up Gmail auto-reply, blocks your calendar, and updates your Slack status in one go.
Meeting follow-up: After a call, your assistant reads the Gemini transcript, summarizes key decisions, and drafts a follow-up email with action items.
(These are just examples - any workflow that needs email search, reading, or sending can use this.)
Setup
1. Create Google OAuth credentials
- Go to Google Cloud Console
- Create a new project (or use existing)
- Enable the Gmail API
- Go to APIs & Services → OAuth consent screen, set up consent screen
- Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
- Choose Web application
- Add
http://localhost:3000/callbackto Authorized redirect URIs - 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
With the server running, follow the instructions on install-mcp, which generates the right config for your MCP client (Claude Code, Claude Desktop, Cursor, Cline, VS Code, and more).
Architecture
This server acts as an OAuth proxy to Google:
graph LR
A[MCP client] <--> B[gmail-mcp] <--> C[Google OAuth/API]
- Server advertises itself as an OAuth authorization server via
/.well-known/oauth-authorization-server /registerreturns the Google OAuth client credentials/authorizeredirects to Google, encoding the client's callback URL in state/callbackreceives the code from Google and forwards to the client's callback/tokenproxies token requests to Google, injecting client credentials/mcphandles 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_forward | Forward an email to new recipients |
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 labelsgmail.send- Send messagesgmail.modify- Modify messages (archive, labels, trash)
Contributing
Pull requests are welcomed on GitHub! To get started:
- Install Git and Node.js
- Clone the repository
- Install dependencies with
npm install - Run
npm run testto run tests - Build with
npm run build
Releases
Versions follow the semantic versioning spec.
To release:
- Use
npm version <major | minor | patch>to bump the version - Run
git push --follow-tagsto push with tags - Wait for GitHub Actions to publish to the NPM registry.