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

---

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