Gmail MCP Setup Guide

Clone the repo and install dependencies. No build step needed — the server runs TypeScript directly via tsx.

git clone https://github.com/coreyepstein/advanced-gmail-mcp
cd advanced-gmail-mcp
npm install

Copy your downloaded OAuth JSON into the repo root and rename it:

cp ~/Downloads/client_secret_*.json ./credentials.json
chmod 600 credentials.json

mkdir -p tokens
chmod 700 tokens

Copy the example config and edit it with your accounts:

cp accounts.example.json accounts.json

Edit accounts.json:

{
  "accounts": [
    {
      "email": "you@gmail.com",
      "alias": "personal",
      "name": "Your Name"
    },
    {
      "email": "support@yourdomain.com",
      "alias": "support",
      "name": "Support Team"
    },
    {
      "email": "admin@yourcompany.com",
      "alias": "work",
      "name": "Work Admin"
    }
  ],
  "default": "personal"
}

Run the auth flow once per account. Each opens a browser URL — sign in and approve, then the token is saved automatically.

# Authenticate one account at a time
npx tsx src/auth.ts personal
npx tsx src/auth.ts work
npx tsx src/auth.ts support

# Or authenticate all accounts in sequence
npx tsx src/auth.ts

# Check status of all accounts
npx tsx src/auth.ts --check

chmod 600 tokens/*.json

Edit your Claude Desktop config at:

~/Library/Application Support/Claude/claude_desktop_config.json

Add a single gmail entry under mcpServers — one server handles all accounts:

{
  "mcpServers": {
    "gmail": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "tsx",
        "/absolute/path/to/advanced-gmail-mcp/src/server.ts"
      ]
    }
  }
}

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

If you're sending from a custom domain alias (e.g. support@yourdomain.com), outbound mail may land in spam. Fix: add Google's sending servers to your domain's SPF record.

dig TXT yourdomain.com +short

Look for a line starting with v=spf1.

Add include:_spf.google.com before the final ~all or -all:

# Before
v=spf1 include:_spf.mx.cloudflare.net ~all

# After
v=spf1 include:_spf.mx.cloudflare.net include:_spf.google.com ~all

Update this in your DNS provider (Cloudflare, Route53, etc.). Propagates in minutes on Cloudflare.

With Claude Desktop restarted, try these prompts:

List the 5 most recent unread emails in my personal inbox.

Send a test email from my work account to yourself at your personal address.
Subject: MCP test. Body: It works.

Search my support inbox for emails from this week that mention "invoice".

cat ~/Library/Logs/Claude/mcp*.log | tail -50

Look for [gmail] Server started and connected successfully. If absent, check the path in your config and that npm install completed cleanly.

Once the MCP is running, you can build a Claude skill that turns a markdown email body into a branded HTML newsletter and sends it to a contact group — all from a single prompt.

• You say "send this to my [group name] list" and paste or describe the content
• The skill calls get_contact_group to fetch all members of a named Google Contacts group
• Converts your markdown body → styled HTML using your own branded template
• Shows a preview (subject, recipient count, snippet) and waits for confirmation
• Sends individually to each member — not BCC — so each person gets a personal send

1. An HTML email template — your branded shell with a {{BODY_HTML}} placeholder where the converted content goes
2. A Google Contacts group — create one in contacts.google.com and add your list members. The group name is what you'll pass to get_contact_group.
3. A skill file (~/.claude/skills/your-newsletter/SKILL.md) — instructs Claude to: collect subject + markdown body, fetch the contact group, convert markdown to HTML, inject into your template, preview, confirm, then send.

Tell Claude in your skill instructions to convert using these patterns:

- Blank line between paragraphs → <p style="margin:0 0 20px 0;">...</p>
- **bold** → <strong>
- *italic* → <em>
- - list item → <ul><li>
- ## heading → <p><strong>heading</strong></p>
- [text](url) → <a href="url">text</a>
- --- → <hr>