Skip to main content
Glama
ustikya

mcp-gmail

by ustikya
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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

  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

  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.

  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 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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

  • sebastianall1977-gmail-mcpOAuth
    ai.smithery

    Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…

    CommunicationApp AutomationWorkplace & Productivity
    2
  • emailA
    dev.primitive

    Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.

    EmailCommunication
    302
  • AIsa Agent MailAOAuth
    one.aisa

    Your agent needs a mailbox of its own — to receive, thread, draft and send, with attachments, without borrowing your personal inbox or your company's SMTP. **What you can ask for** • "Create an inbox for this agent and tell me its address." • "Read the new messages in this thread and draft a reply." • "Send this message with the attachment and wait for the response." • "Search this inbox for everything from that domain." • "Show delivery metrics and the events on this inbox." **How to use it** Point any MCP client at https://mcp.aisa.one/mail/mcp and sign in with OAuth — there is no key to create or paste. 49 tools: create and delete inboxes, list and read messages, raw message bodies, attachments, threads, drafts and draft attachments, send and reply, message search, inbox events, metrics, and list entries — reads and writes. **Why this rather than the source** A real inbox an agent owns, rather than an SMTP credential it borrows from a human. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the contact elsewhere in the catalogue, then write to them from here — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/sales/mcp finds the person to write to.

    App AutomationEmail
    541
  • faithk7-gmail-mcpOAuth
    ai.smithery

    Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…

    CommunicationApp AutomationWorkplace & Productivity
    2