gmail-mcp
MCP server for Gmail - read, send, archive, and manage emails.
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
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]
- 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_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)
Development
npm install
npm run build
npm run lint
npm test
