Skip to main content
Glama
Paviyarasanmani

Gmail MCP Server

by Paviyarasanmani
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Gmail MCP Server

A custom MCP server that gives Claude full Gmail control — send directly (no drafts), read, reply, search, label, and delete — over stdio for Claude Desktop and Cowork.

Folder Structure

gmail-mcp-server/
├── src/
│   ├── server.ts            ← MCP entry point, registers all tools
│   ├── auth.ts              ← OAuth2 flow + token refresh
│   ├── gmail-client.ts      ← Gmail API wrapper
│   ├── templates.ts         ← HTML email templates
│   ├── config.ts            ← Env var loader
│   ├── logger.ts            ← Structured stderr logger
│   └── tools/
│       ├── send-email.ts         ← send_email
│       ├── send-bulk-email.ts    ← send_bulk_email
│       ├── send-template-email.ts← send_template_email + list_templates
│       ├── list-emails.ts        ← list_emails, get_email, reply_email
│       └── search-emails.ts      ← search_emails, list_labels, add_label, move_email, delete_email
├── .env.example
├── claude_desktop_config.example.json
├── tsconfig.json
└── package.json

Related MCP server: gmail-mcp

Step 1 — Google Cloud Console Setup (One-time)

  1. Go to https://console.cloud.google.com

  2. Create a new project (or use existing)

  3. Enable the Gmail API:

    • APIs & Services → Library → search "Gmail API" → Enable

  4. Create OAuth2 credentials:

    • APIs & Services → Credentials → Create Credentials → OAuth client ID

    • Application type: Desktop app

    • Name: gmail-mcp-server

    • Click Create → Copy the Client ID and Client Secret

  5. Configure OAuth consent screen:

    • OAuth consent screen → External → Add your Gmail as a test user

    • Add scopes: gmail.send, gmail.readonly, gmail.modify

Step 2 — Project Setup

# 1. Install dependencies
npm install

# 2. Create your .env file
cp .env.example .env

# 3. Edit .env and fill in your credentials
#    GOOGLE_CLIENT_ID=your_client_id
#    GOOGLE_CLIENT_SECRET=your_client_secret
#    SENDER_NAME=Your Name

Step 3 — Authenticate (One-time)

npm run auth

This will:

  1. Print a Google auth URL

  2. You open it in your browser, sign in, approve permissions

  3. Paste the code back into the terminal

  4. token.json is saved — never needs to be repeated

Step 4 — Build

npm run build

This compiles TypeScript → dist/ folder.

Step 5 — Connect to Claude Desktop

Edit your Claude Desktop config file:

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

Add the gmail server block (replace paths with your actual absolute paths):

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/Users/yourname/gmail-mcp-server/dist/server.js"],
      "env": {
        "GOOGLE_CLIENT_ID":     "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "TOKEN_PATH":           "/Users/yourname/gmail-mcp-server/token.json",
        "SENDER_NAME":          "Your Name",
        "LOG_LEVEL":            "info"
      }
    }
  }
}

Restart Claude Desktop. The gmail tools will appear in Claude's tool list.

Step 6 — Connect to Cowork

In Cowork, add a local MCP server with:

  • Command: node /absolute/path/to/gmail-mcp-server/dist/server.js

  • Environment variables: same as above

Available Tools

Tool

What it does

send_email

Send directly to one or more recipients

send_bulk_email

Send same email to up to 50 recipients

send_template_email

Send HTML email using a template

list_templates

See all templates and their variables

list_emails

List inbox / any label with optional query

get_email

Read full email by message ID

reply_email

Reply in-thread to an email

search_emails

Full Gmail search query support

list_labels

See all labels and their IDs

add_label

Add labels to an email

move_email

Move / archive / mark read

delete_email

Move to Trash

Example Prompts for Claude

Send an email to john@example.com with subject "Hello" and body "Let's connect!"

Search my emails for invoices from last month

Reply to message ID <id> saying "Thanks, I'll review this today"

Send the welcome template to sarah@example.com with name="Sarah" and company="Acme"

List my unread emails in INBOX

Move email <id> to archive (remove INBOX label)

Adding New Templates

Edit src/templates.ts and add a new entry to the TEMPLATES object. Then rebuild: npm run build

Development (no build needed)

npm run dev   # runs via tsx directly

Troubleshooting

Problem

Fix

Missing required env var

Check your .env file or the env block in Claude Desktop config

Token expired

Run npm run auth again

Permission denied on Gmail API

Make sure Gmail API is enabled in Google Cloud Console

Claude doesn't see tools

Restart Claude Desktop after editing config

Server crashes silently

Check LOG_LEVEL=debug and watch stderr output

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

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-gmail

    knowledgeislands
    A
    license
    B
    quality
    F
    maintenance
    MCP server that connects Claude with Gmail to read, send, delete, and manage messages and labels via the Google Gmail API.
    3
    MIT

  • gmail-mcp-server

    ndungukamami-sketch
    A
    license
    Not graded
    quality
    D
    maintenance
    A secure MCP server that enables Claude to read, search, send, reply, forward, and manage Gmail messages and labels through natural language commands.
    62 npm
    1
    MIT