gmail-mcp-server

Gmail MCP Server — read, send, search, and manage Gmail through Claude using Google's official API.

19 tools for emails, drafts, labels, threads, and attachments — powered by the official Google Gmail API with OAuth 2.0. Works with any Google account (personal Gmail or Google Workspace).

Tools

Email Operations (5)

| Tool | Description | |------|-------------| | gmail_search | Search emails using Gmail query syntax | | gmail_get_message | Get full email content by ID | | gmail_send | Send an email (supports CC, BCC, reply threading) | | gmail_get_thread | Get all messages in a thread | | gmail_get_profile | Get your Gmail profile info |

Drafts (4)

| Tool | Description | |------|-------------| | gmail_create_draft | Create a draft email | | gmail_list_drafts | List all saved drafts | | gmail_send_draft | Send an existing draft | | gmail_delete_draft | Delete a draft |

Labels (3)

| Tool | Description | |------|-------------| | gmail_list_labels | List all labels | | gmail_create_label | Create a new label | | gmail_delete_label | Delete a label |

Message Management (4)

| Tool | Description | |------|-------------| | gmail_trash | Move email to trash | | gmail_untrash | Restore email from trash | | gmail_mark_read | Mark email as read | | gmail_mark_unread | Mark email as unread | | gmail_modify_labels | Add or remove labels from an email |

Attachments (2)

| Tool | Description | |------|-------------| | gmail_list_attachments | List all attachments in an email | | gmail_get_attachment | Download attachment as base64 |

Setup

This server uses Google's official Gmail API. You need to create OAuth 2.0 credentials once in Google Cloud Console — this takes about 5 minutes.

Step 1 — Create a Google Cloud Project

1. Go to console.cloud.google.com
2. Click the project dropdown at the top → "New Project"
3. Give it a name (e.g. gmail-mcp) and click Create
4. Make sure the new project is selected

Step 2 — Enable the Gmail API

1. In the left menu go to "APIs & Services" → "Library"
2. Search for "Gmail API"
3. Click it → click "Enable"

Step 3 — Configure OAuth Consent Screen

1. Go to "APIs & Services" → "OAuth consent screen"
2. Choose "External" (works for any Google account) → click Create
3. Fill in:
   • App name: Gmail MCP Server (or anything)
   • User support email: your email
   • Developer contact email: your email
4. Click Save and Continue
5. On the Scopes page, click "Add or Remove Scopes" and add these:

   https://www.googleapis.com/auth/gmail.readonly
   https://www.googleapis.com/auth/gmail.send
   https://www.googleapis.com/auth/gmail.compose
   https://www.googleapis.com/auth/gmail.modify
   https://www.googleapis.com/auth/gmail.labels

6. Click Save and Continue
7. On Test users, click "Add Users" → add your Gmail address
8. Click Save and Continue → Back to Dashboard

Step 4 — Create OAuth Client ID

1. Go to "APIs & Services" → "Credentials"
2. Click "+ Create Credentials" → "OAuth client ID"
3. Application type: "Desktop app"
4. Name: Gmail MCP Server
5. Click Create
6. Click "Download JSON" — save this file, you'll need it next

Step 5 — Install & Authenticate

# Install the package
npm install -g @dev-hitesh-gupta/gmail-mcp-server

# Install dependencies for first run
npx playwright install chromium 2>/dev/null; true

# Create config directory and place your credentials
mkdir -p ~/.gmail-mcp
cp /path/to/downloaded-credentials.json ~/.gmail-mcp/credentials.json

# Authenticate — opens a browser window for Google sign-in
gmail-mcp-server auth

Your token is saved to ~/.gmail-mcp/token.json and auto-refreshed on expiry.

Step 6 — Add to Claude Code

claude mcp add gmail -- npx @dev-hitesh-gupta/gmail-mcp-server

Or manually in your Claude config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["@dev-hitesh-gupta/gmail-mcp-server"]
    }
  }
}

Multiple Accounts

You can connect multiple Gmail accounts by running separate server instances with different config directories:

{
  "mcpServers": {
    "gmail-work": {
      "command": "npx",
      "args": ["@dev-hitesh-gupta/gmail-mcp-server"],
      "env": { "GMAIL_MCP_CONFIG_DIR": "~/.gmail-mcp-work" }
    },
    "gmail-personal": {
      "command": "npx",
      "args": ["@dev-hitesh-gupta/gmail-mcp-server"],
      "env": { "GMAIL_MCP_CONFIG_DIR": "~/.gmail-mcp-personal" }
    }
  }
}

Authenticate each separately:

GMAIL_MCP_CONFIG_DIR=~/.gmail-mcp-work gmail-mcp-server auth
GMAIL_MCP_CONFIG_DIR=~/.gmail-mcp-personal gmail-mcp-server auth

Gmail Search Syntax

The gmail_search tool supports the full Gmail query language:

from:[email protected]           # From specific sender
to:me                           # Sent to you
subject:invoice                 # Subject contains word
is:unread                       # Unread emails
is:starred                      # Starred emails
has:attachment                  # Has attachments
after:2024/01/01                # After date
before:2024/12/31               # Before date
label:work                      # Has label
in:inbox                        # In inbox
in:sent                         # In sent
in:spam                         # In spam

Combine queries:

from:[email protected] is:unread has:attachment
subject:urgent OR subject:important
from:[email protected] after:2024/06/01

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | GMAIL_MCP_CONFIG_DIR | ~/.gmail-mcp | Directory for credentials and token |

Data & Auth Storage

All data is stored locally:

~/.gmail-mcp/
├── credentials.json    # Your Google OAuth client credentials
└── token.json          # Access + refresh token (auto-managed)

Security: Never commit credentials.json or token.json to version control. Add ~/.gmail-mcp/ to your .gitignore.

Troubleshooting

"Not authenticated" / "Credentials not found":

# Make sure credentials.json is in place
ls ~/.gmail-mcp/credentials.json

# Re-authenticate
gmail-mcp-server auth

Token expired:

rm ~/.gmail-mcp/token.json
gmail-mcp-server auth

"Access blocked" during Google sign-in: Your OAuth app is in test mode. Go to Google Cloud Console → OAuth consent screen → add your email under Test users.

Scope errors: Ensure all 5 Gmail scopes are added in the OAuth consent screen (Step 3 above).

Requirements

• Node.js 18+
• A Google account (personal Gmail or Google Workspace)
• Google Cloud project with Gmail API enabled (see setup above)

License

MIT — Hitesh Gupta