Gmail MCP Server

Local setup required. This server has to be cloned and prepared on your machine before you register it in Claude Code.
1

Set the server up locally

Run this once to clone and prepare the server before adding it to Claude Code.

Run in terminal
git clone https://github.com/user/mcp-gmail.git
cd mcp-gmail
bun install
bun run auth
2

Register it in Claude Code

After the local setup is done, run this command to point Claude Code at the built server.

Run in terminal
claude mcp add mcp-gmail -- bun "<FULL_PATH_TO_MCP_GMAIL>/dist/index.js"

Replace <FULL_PATH_TO_MCP_GMAIL>/dist/index.js with the actual folder you prepared in step 1.

README.md

Give Claude full access to your Gmail.

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)
  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
Configure OAuth consent screen
  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.

Create OAuth credentials
  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

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 du

Tools (18)

search_emailsSearch using Gmail query syntax
get_emailGet full content by message ID
send_emailSend a new email
reply_to_emailReply to an email (preserves thread)
forward_emailForward to new recipients
create_draftCreate a new draft
list_draftsList all drafts
send_draftSend an existing draft
delete_draftPermanently delete a draft
trash_emailMove to trash
archive_emailRemove from inbox
mark_as_readMark as read
mark_as_unreadMark as unread
list_labelsList all labels
create_labelCreate a new label
apply_labelApply a label to a message
remove_labelRemove a label from a message
get_attachmentDownload attachment (base64)

Configuration

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

Try it

→Search my inbox for emails from Sarah this week.
→Draft a reply to that meeting invite I received this morning.
→Archive all read emails currently labeled 'notifications'.
→Forward the latest invoice from my inbox to accounting@company.com.
→List all my current drafts and send the one about the project update.

Frequently Asked Questions

What are the key features of Gmail MCP?

Full Gmail search capabilities using standard Gmail query operators.. Comprehensive email management including sending, replying, and forwarding.. Draft management for creating, listing, and sending emails.. Label organization tools to categorize and manage messages.. Attachment handling to download files directly from emails..

What can I use Gmail MCP for?

Automating the sorting and archiving of routine notification emails.. Quickly drafting and sending professional replies to meeting invites without leaving the chat interface.. Extracting and forwarding specific invoices or documents to accounting departments.. Managing email labels to keep an inbox organized through natural language commands..

How do I install Gmail MCP?

Install Gmail MCP by running: git clone https://github.com/user/mcp-gmail.git && cd mcp-gmail && bun install && bun run auth

What MCP clients work with Gmail MCP?

Gmail MCP works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Turn this server into reusable context

Keep Gmail MCP docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Need the old visual installer? Open Conare IDE.
Open Conare
View all communication servers →

Related MCP Servers

Vexa
Self-hosted meeting intelligence platform
communication1.8K stars
Claude Peers
Let your Claude Code instances find each other and talk.
communication1.8K stars
Wenyan MCP Server
Bridge AI writing and WeChat Official Account publishing with Markdown.
communication1.1K stars
KeyID Agent Kit
Give Claude, Cursor, or any MCP client a real email address. Free.
communication546 stars
Instagram MCP Server
Integrate with Instagram's Graph API for AI-driven account management.
communication93 stars
WeChat MCP Server
A WeChat robot server that enables AI agents to send and receive messages.
communication78 stars