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

Create project & enable Gmail API (click to expand)

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

Configure OAuth consent screen

Go to APIs & Services → OAuth consent screen
Click Create on the Overview tab
Fill in App name and User support email
Select External → Create
Data access tab → Add or Remove Scopes → find https://www.googleapis.com/auth/gmail.modify → check it → Update → Save
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.

Create OAuth credentials

Go to APIs & Services → Credentials
Create Credentials → OAuth client ID → Desktop app
Click Create → Download JSON
Save as credentials.json in the project root

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

mcp-gmail

mcp-gmail

What you can do

Quick Start

Prerequisites

1. Google Cloud setup

2. Install & authenticate

3. Add to Claude Desktop

Tools

Email

Drafts

Organization

Labels

Attachments

Gmail Search Syntax

Troubleshooting

License

Reviews