MCP Server · v1.2.0
Your inbox, managed by Claude.
Search, organize, label, filter, and send email from Claude Code. Outbound email requires human approval via Slack before anything is sent. Triage mode monitors your inbox and handles the noise for you.
Full inbox management. Human in the loop.
Gmail MCP gives Claude the ability to read, organize, and send email from your inbox. Sending requires human approval: the draft is posted to your Slack channel, and nothing leaves your outbox until you reply APPROVE in the thread.
The move_to_folder tool blocks TRASH as a target. The create_filter tool blocks TRASH routing. OAuth scopes are limited to modify, labels, settings, and send. No delete. No trash. Outbound email always waits for your sign-off.
// "catch me up on today's email"
list_emails({query: "newer_than:1d"})
12 emails today — 4 unread
read_email({id: "msg_8f2a"})
from: AWS — your invoice for March is ready
apply_label({message_ids: ["msg_8f2a"], label_ids: ["Label_9"]})
labeled "Billing"
archive({message_ids: ["msg_8f2a"]})
archived 1 email
What people use it for.
Catch up on backlogs
"Summarize what I missed this week." Claude reads through your unread emails and gives you the highlights — without you opening a single one.
Triage without reading
"Label anything from GitHub as Engineering and archive marketing emails." Bulk organize your inbox based on rules you describe in plain language.
Find anything instantly
"Find the API key that Sarah emailed me last month." Search years of email with natural language — no more guessing at Gmail search operators.
Set up smart filters
"Create a filter for all receipts -- label them and skip the inbox." Claude spots patterns in your email and builds Gmail filters to handle them automatically.
Send with approval
"Reply to Sarah confirming the meeting." Claude drafts the email and posts it to your Slack channel. You review and reply APPROVE or REJECT. Nothing sends without your sign-off.
Autonomous triage
"Manage my inbox." Claude monitors incoming mail, archives junk, labels important messages, stars things that need your attention, and drafts replies for your approval.
Triage mode.
Run /gmail:triage and Claude becomes a long-running inbox manager. It monitors your email via channel events, processes new messages as they arrive, and learns your preferences over time.
Auto-archive junk
Marketing blasts, notification spam, and newsletters you never open get archived automatically. Claude learns what you ignore and handles it.
Label and star
Important mail gets labeled and starred. Claude categorizes incoming messages based on sender, content, and your past behavior.
Draft replies with approval
When a message needs a response, Claude drafts a reply and sends it to Slack for your approval. You review, approve or reject, and move on.
Propose filters
Spots recurring patterns and proposes Gmail filters to handle them permanently. Filters are created only after you confirm.
Learn preferences
Stores learned rules in email-rules.json. Over time, triage gets faster and more accurate as it adapts to how you handle email.
Channel-driven
Pairs with the email-triage channel MCP, which polls your inbox every 5 minutes and fires events into the session. No manual triggering needed.
Safe by design.
Gmail MCP is built around controlled access. Claude can read, organize, and send email, but outbound messages always require human approval via Slack. No destructive operations exist.
Approval-gated sending
The send_email tool posts the full draft to your Slack channel and polls the thread for APPROVE or REJECT. Nothing is sent until you explicitly approve. Rejection cancels the send entirely.
No destructive tools
There is no delete or trash tool. move_to_folder rejects TRASH as a target. create_filter rejects filters that route to TRASH. Nothing leaves your mailbox.
Scoped OAuth
Requests gmail.modify, gmail.labels, gmail.settings.basic, and gmail.send. No full-access scope. Tokens stored locally, auto-refresh, never transmitted.
16 tools.
Everything you need to read, organize, and send. Outbound email is approval-gated. Nothing can delete or trash.
list_emails
Search or list emails using Gmail query syntax. Returns subjects, senders, dates, labels, and snippets.
read_email
Read the full body of a specific email. Extracts text content with subject, sender, and date.
list_labels
List all Gmail labels — system and user-created — with IDs and types.
create_label
Create a new label. Supports nesting with / (e.g. Projects/ClientA).
apply_label
Apply labels to emails in bulk. One call, many messages.
remove_label
Remove labels from emails in bulk.
archive
Archive emails — removes from inbox, stays in All Mail.
mark_read / mark_unread
Toggle read status on one or many emails.
star
Star or unstar emails for quick access.
move_to_folder
Move emails between folders. TRASH is blocked as a target.
list_filters
List all Gmail filters with their criteria and actions.
create_filter
Create auto-labeling and routing filters. TRASH routing is blocked.
delete_filter
Remove a filter that's no longer needed.
send_email
Compose and send email with human approval. Posts draft to Slack, polls for APPROVE/REJECT before sending.
channel_status
Check the status of the email-triage channel connection and event polling.
Install
Requires Node.js and a Google Cloud OAuth2 client credential.
Add the marketplace
claude plugin marketplace add softwaresoftware-dev/softwaresoftware-plugins
Run in your terminal.
Install the installer
claude plugin install softwaresoftware@softwaresoftware-plugins
Run in your terminal.
Launch Claude Code and install
/softwaresoftware:install gmail-mcp
Run inside Claude Code.
Or clone manually: git clone https://github.com/softwaresoftware-dev/gmail-mcp && cd gmail-mcp && npm install && npm run build
Set up Google Cloud credentials
Create a project in Google Cloud Console, enable the Gmail API, create OAuth2 Desktop credentials, and save the JSON as credentials.json in the project root. The OAuth consent screen may show an "unverified app" warning while Google review is pending. This does not block functionality.
Authenticate with Gmail
npm run auth
Opens a browser window for OAuth2 consent. Stores the refresh token locally in token.json. Tokens auto-refresh — you only need to do this once.