mcp-gmail

Give Claude full access to your Gmail. Search, read, send, reply, forward, manage drafts, labels, and attachments — all through the Model Context Protocol.

What you can do

"Search my inbox for emails from Sarah this week" "Draft a reply to that meeting invite" "Archive all read emails labeled 'notifications'" "Forward the latest invoice to accounting@company.com"

17 tools covering everything you'd do in Gmail — without leaving Claude.

---

Quick Start

Prerequisites

• Bun runtime
• A Google account with Gmail

1. Google Cloud setup

<details> <summary><b>Create project & enable Gmail API</b> (click to expand)</summary>

1. Go to Google Cloud Console
2. Select a project → New Project → name it (e.g., "Gmail MCP") → Create
3. Go to APIs & Services → Library → search Gmail API → Enable </details>

<details> <summary><b>Configure OAuth consent screen</b></summary>

1. Go to APIs & Services → OAuth consent screen
2. Click Create on the Overview tab
3. Fill in App name and User support email
4. Select External → Create
5. Data access tab → Add or Remove Scopes → find https://www.googleapis.com/auth/gmail.modify → check it → Update → Save
6. Users tab → Add Users → add your Gmail address → Save

Tip: In "Testing" mode, refresh tokens expire every 7 days. To avoid this, go to Publishing status → Publish App. For personal use, Google won't require verification. </details>

<details> <summary><b>Create OAuth credentials</b></summary>

1. Go to APIs & Services → Credentials
2. Create Credentials → OAuth client ID → Desktop app
3. Click Create → Download JSON
4. Save as credentials.json in the project root </details>

2. Install & authenticate

git clone https://github.com/user/mcp-gmail.git  # replace with your repo URL
cd mcp-gmail
bun install
bun run auth    # opens browser for Gmail authorization

Tokens are saved locally to .gmail-tokens.json (git-ignored).

3. Add to Claude Desktop

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gmail": {
      "command": "bun",
      "args": ["/ABSOLUTE/PATH/TO/mcp-gmail/src/index.ts"]
    }
  }
}

Note: Claude Desktop doesn't inherit your shell PATH. If bun isn't found, use the full path — run which bun to find it.

Restart Claude Desktop. You should see gmail in the MCP servers list.

---

Tools

Email

Tool	Description
search_emails	Search using Gmail query syntax
get_email	Get full content by message ID
send_email	Send a new email
reply_to_email	Reply to an email (preserves thread)
forward_email	Forward to new recipients

Drafts

Tool	Description
create_draft	Create a new draft
list_drafts	List all drafts
send_draft	Send an existing draft
delete_draft	Permanently delete a draft

Organization

Tool	Description
trash_email	Move to trash
archive_email	Remove from inbox
mark_as_read	Mark as read
mark_as_unread	Mark as unread

Labels

Tool	Description
list_labels	List all labels
create_label	Create a new label
apply_label	Apply a label to a message
remove_label	Remove a label from a message

Attachments

Tool	Description
get_attachment	Download attachment (base64)

---

Gmail Search Syntax

The search_emails tool supports all Gmail search operators:

from:alice@example.com          # From specific sender
to:bob@example.com              # To specific recipient
subject:meeting                 # Subject contains "meeting"
has:attachment                  # Has attachments
is:unread                       # Unread emails
is:starred                      # Starred emails
label:important                 # Has label
after:2024/01/01                # After date
before:2024/12/31               # Before date
newer_than:7d                   # Last 7 days
"exact phrase"                  # Exact match
from:alice subject:report       # Combine operators

---

Troubleshooting

Problem	Solution
credentials.json not found	Download OAuth credentials from Google Cloud Console
.gmail-tokens.json not found	Run bun run auth
Token has been revoked	Re-run bun run auth
Refresh token expired	App is in "Testing" mode — re-run bun run auth or publish the app
Insufficient permissions	Ensure gmail.modify scope was granted during auth
Server not appearing in Claude	Check the config path is absolute, then restart Claude Desktop
Port 3000 is already in use	Free port 3000 and re-run bun run auth

License

Apache 2.0