Build an AI Inbox Triage Agent with Claude Desktop and Gmail MCP

A 200-message inbox takes 60–90 minutes to process manually. With Claude Desktop wired to a Gmail MCP server, the same inbox processes in 10 minutes with human approval on each action. This is one of the most practically useful agent builds available right now — the setup time is low, the tooling is mature, and the time savings compound daily.

This guide walks through the complete setup: installation, OAuth configuration, the four-bucket triage taxonomy, and how to handle the three failure modes that break most first-time builds.

The timing claim — 10 minutes versus 60–90 minutes for a 200-message backlog — comes from documented practitioner experience, not from a test we ran. The claim is specific enough to be verifiable on your own inbox, which is the appropriate way to assess it.

Want the ready-to-use files? The Inbox Triage Kit packages everything from this guide into a copy-paste SKILL.md, MCP server config examples for three paths, and four prompt templates tuned to different inbox profiles. The free sample (SKILL.md + 2-page quickstart) is a direct download — no email required.

What you are building

An agent that reads your Gmail inbox, categorizes each message into one of four buckets (Reply, Delegate, Defer, Delete), and surfaces only the messages that need your attention with a one-line summary and a suggested action. You approve each action before it executes. In the first month, no autonomous sends.

The setup has three components:

1. Claude Desktop — the agent runtime with a built-in MCP client
2. A Gmail MCP server — gives Claude read/write access to your inbox via OAuth
3. A four-bucket triage prompt — the editorial layer that turns Claude’s email access into structured inbox management

Step 1: Find and install a Gmail MCP server

Claude Desktop’s MCP client supports any community-maintained MCP server via a single JSON config entry in claude_desktop_config.json. The setup friction is OAuth browser consent — that is the only complex step.

The primary places to find Gmail/email MCP servers as of July 2026 are the official MCP Registry (registry.modelcontextprotocol.io), Smithery (7,000+ servers with one-click install and OAuth management), and MCP.so (19,000+ community-submitted servers, the largest catalogue).

For Gmail specifically, search “gmail” on Smithery first — Smithery’s one-click install handles the OAuth flow interactively, which reduces the manual config steps for first-time builders. If the Smithery-hosted version does not fit your requirements, fall back to a self-hosted server found via MCP.so or the official registry.

Once you have chosen a server, the config entry in claude_desktop_config.json follows this pattern (adjust the command and args per the server’s README):

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@your-chosen-gmail-mcp-package"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart Claude Desktop after editing the config. The MCP indicator in the interface will show the Gmail server as connected.

Step 2: OAuth setup

The Gmail MCP server needs a Google OAuth app with Gmail API scope enabled. The standard path:

1. Go to Google Cloud Console — APIs and Services — Credentials
2. Create an OAuth 2.0 Client ID for a Desktop App
3. Enable the Gmail API in the same project
4. Add the client ID and secret to your MCP server config
5. On first run, a browser consent screen appears — approve it

This is the only step that requires careful attention. Most setup failures are OAuth scope mismatches or a missing Gmail API enable step. If Claude can see the MCP server but reads fail, check that https://mail.google.com/ is in the approved scopes, not just the read-only scope.

Step 3: The four-bucket triage prompt

The taxonomy is the editorial layer. Without a clear prompt, Claude will read email and produce undifferentiated summaries. The four-bucket system forces a decision on every message:

• Reply — needs a response from you, today or soon
• Delegate — someone else should handle this; you may need to forward or note it
• Defer — real but not urgent; add to a follow-up list
• Delete — no action needed, can be archived or deleted

The prompt structure that works in production (documented in practitioner builds):

You are an inbox triage assistant. For each email, assign exactly one of: REPLY, DELEGATE, DEFER, DELETE.

Output format for each email:
- Subject: [subject]
- Bucket: [REPLY/DELEGATE/DEFER/DELETE]
- Reason: [one sentence]
- Suggested action: [specific next step]

Hard exclusions — never suggest autonomous action on:
- Legal matters or anything from an attorney
- Financial transactions or invoices over $500
- Emails from unknown senders with file attachments
- Messages containing: contract, lawsuit, settlement, payment, wire

For excluded messages: bucket as DEFER and note "HUMAN REVIEW REQUIRED".

The hard exclusions are not optional. They are documented best practice from every serious inbox agent implementation. The consequences of an agent autonomously acting on a legal email are significant enough that the exclusion list should be longer, not shorter, when you are starting out.

Step 4: The first-month rule — no autonomous send

The Claude Agent SDK cookbook pattern for stateless queries — async for msg in query(prompt=..., options=ClaudeAgentOptions(allowed_tools=["WebSearch"])) — applies directly to inbox triage when the tools list is swapped for Gmail MCP tools. The key architectural choice for your first month: keep the agent in suggestion mode, not autonomous mode.

This means: Claude reads, categorizes, and drafts. You approve and send. You do not wire the Gmail MCP write tool to fire automatically on any condition. The reason is practical, not philosophical: you will discover edge cases in your exclusion list, prompt gaps for your specific email patterns, and false positives in the first week. Running in suggestion mode lets you iterate without consequences.

After 30 days of reviewing suggestions, you will have enough ground truth to know which buckets are safe to automate. Most practitioners report that Delete and Defer can be automated safely after the first month; Reply almost never should be.

The three common failure modes

Failure mode 1: OAuth scope too narrow. Symptom: Claude can list inbox subjects but cannot read message bodies or modify labels. Fix: ensure your OAuth scope includes https://mail.google.com/ (full access), not just gmail.readonly. The readonly scope is insufficient for triage because you cannot move or label messages.

Failure mode 2: Exclusion list too short. Symptom: Claude suggests an action on a message that obviously needs human review. Fix: extend the exclusion list. Add any domain or sender that has ever sent you something legally or financially significant. The list should err toward caution — a false exclusion costs 30 seconds of your time; a false inclusion can cost much more.

Failure mode 3: Volume overload on first run. Symptom: You point Claude at a 5,000-message inbox and the session runs out of context or produces an unusable wall of output. Fix: scope the first run. Use a date filter to restrict to the last 7 days, or a label filter to a specific inbox folder. Build confidence on a small slice before expanding scope.

Cost expectations

The inbox triage build has a near-zero ongoing infrastructure cost. Claude Desktop is free. The Gmail MCP server (self-hosted or Smithery-hosted) is free. The only cost is Claude API usage if you are using the API directly rather than Claude Desktop — and for a 200-message daily triage, that cost is typically under $1/day at current API pricing.

Common questions

Does this work with email providers other than Gmail?

The same approach works with any email provider that has an MCP server implementation. As of July 2026, Smithery and MCP.so list MCP servers for Outlook/Microsoft 365, ProtonMail, and several other providers. The triage prompt and four-bucket taxonomy are provider-agnostic — only the OAuth setup and MCP server config change.

What is the difference between this and a dedicated inbox AI tool like Superhuman?

Dedicated tools like Superhuman have better polish and do not require any setup. The MCP-based approach gives you more control over the triage logic and keeps processing local. The right choice depends on whether you want a product (buy Superhuman) or a configurable agent you own (build this). Both are legitimate choices.

Can I run this as an always-on background agent?

The Claude Agent SDK supports stateful ClaudeSDKClient patterns for multi-turn and ongoing workflows. Running inbox triage as a background agent that checks for new messages on a schedule is architecturally feasible but requires moving beyond Claude Desktop into a deployed SDK setup. The desktop build in this guide is the right starting point — get the triage logic right locally before deploying it.

How do I handle email threads vs individual messages?

Most Gmail MCP servers expose threads as the primary unit. The triage prompt works better at the thread level than the individual message level — one bucket assignment per thread, with the most recent message as the primary context. If your MCP server exposes individual messages, add "treat each thread as a unit" to your system prompt.