Shravan1610/Gmail-mcp-server

Gmail MCP Server

You know that moment when you spot a typo in an email AFTER you sent it to your boss?

Yeah. I hate that feeling.

That ends now.

A Model Context Protocol (MCP) server that lets Claude AI draft, review, and send your emails automatically. Zero typos. Zero embarrassing mistakes. Zero "please disregard my last email" moments.

What This Does

This MCP server gives Claude AI full access to your Gmail, allowing it to:

✅ Draft emails - Let AI write professional emails for you ✅ Review for typos/tone - AI checks grammar, spelling, and tone before sending ✅ Send on your behalf - AI sends emails directly from your Gmail ✅ Search & organize - Find emails, manage labels, star important messages ✅ Reply to threads - Maintain conversation context automatically

No more typo anxiety. No more "oh shit" moments.

Prerequisites

Before you start, make sure you have:

• Docker Desktop installed (Download here)
• Claude Desktop app installed (Download here)
• A Gmail account (the one you want to connect)
• 30 minutes of setup time (one-time only)

That's it. No coding required.

Step-by-Step Setup Guide

Part 1: Google Cloud Setup (15 minutes)

This sets up the connection between the server and your Gmail.

Step 1.1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click "Select a project" dropdown at the top
3. Click "New Project"
4. Name it: gmail-mcp-server (or whatever you want)
5. Click "Create"

Step 1.2: Enable Gmail API

1. In the search bar at top, type "Gmail API"
2. Click on "Gmail API" in the results
3. Click the blue "Enable" button
4. Wait ~30 seconds for it to activate

Step 1.3: Create OAuth Credentials

1. Click "Credentials" in the left sidebar
2. Click "+ Create Credentials" at the top
3. Select "OAuth client ID"
4. If prompted about consent screen:
   • Click "Configure Consent Screen"
   • Select "External" → Click "Create"
   • App name: Gmail MCP Server
   • User support email: Your email
   • Developer contact: Your email
   • Click "Save and Continue" through all steps
   • Click "Back to Dashboard"
5. Now create the OAuth client:
   • Application type: "Web application"
   • Name: gmail-mcp-client
   • Click "Create"
6. IMPORTANT: A popup shows your credentials:
   • Copy the Client ID (save to a text file)
   • Copy the Client Secret (save to a text file)
   • Click "Download JSON" (we'll use this later)

Step 1.4: Get Your Refresh Token

This is the key that lets the server access your Gmail long-term.

Easy Method (using OAuth Playground):

1. Go to OAuth 2.0 Playground
2. Click the ⚙️ gear icon (top right)
3. Check "Use your own OAuth credentials"
4. Paste your Client ID and Client Secret from Step 1.3
5. Close the settings
6. In "Step 1" on the left:
   • Scroll down to "Gmail API v1"
   • Check these 3 boxes:
     • ✅ https://www.googleapis.com/auth/gmail.modify
     • ✅ https://www.googleapis.com/auth/gmail.send
     • ✅ https://www.googleapis.com/auth/gmail.readonly
7. Click blue "Authorize APIs" button
8. Sign in with your Gmail account
9. Click "Allow" when asked for permissions
10. In "Step 2", click "Exchange authorization code for tokens"
11. COPY THE REFRESH TOKEN - save it to your text file
    • It looks like: 1//0gXXXXXXXXXXXXXXXX

✅ Part 1 Complete! You now have:

• Client ID
• Client Secret
• Refresh Token

Save these somewhere safe. You'll need them in Part 2.

Part 2: Docker Setup (10 minutes)

This installs the server on your computer.

Step 2.1: Enable Docker MCP Toolkit

1. Launch Docker Desktop
2. Wait for it to say "Docker Desktop is running" (green icon)
3. Click the Settings icon (⚙️ gear icon in top right)
4. Go to Beta Features in the left sidebar
5. Find "Enable Docker MCP Toolkit" and toggle it ON
6. Click "Apply & Restart"
7. Wait for Docker to restart (~30 seconds)

Step 2.2: Download This Repository

Option A: Using Git (if you have it)

git clone https://github.com/yourusername/gmail-mcp-server.git
cd gmail-mcp-server

Option B: Download ZIP

1. Click green "Code" button on GitHub
2. Click "Download ZIP"
3. Extract the ZIP file
4. Open Terminal/Command Prompt
5. Navigate to the extracted folder:

   cd path/to/gmail-mcp-server
   

Step 2.3: Store Your Credentials as Secrets

Open Terminal/Command Prompt and run these commands one at a time:

# Store Client ID (replace YOUR_CLIENT_ID with the actual value)
docker mcp secret create GMAIL_CLIENT_ID "YOUR_CLIENT_ID"

# Store Client Secret (replace YOUR_CLIENT_SECRET with the actual value)
docker mcp secret create GMAIL_CLIENT_SECRET "YOUR_CLIENT_SECRET"

# Store Refresh Token (replace YOUR_REFRESH_TOKEN with the actual value)
docker mcp secret create GMAIL_REFRESH_TOKEN "YOUR_REFRESH_TOKEN"

Example:

docker mcp secret create GMAIL_CLIENT_ID "123456789-abc123def456.apps.googleusercontent.com"
docker mcp secret create GMAIL_CLIENT_SECRET "GOCSPX-aBc123DEf456Ghi789"
docker mcp secret create GMAIL_REFRESH_TOKEN "1//0gXXXXXXXXXXXXXXXX"

Verify secrets are saved:

docker mcp secret list

You should see:

GMAIL_CLIENT_ID
GMAIL_CLIENT_SECRET
GMAIL_REFRESH_TOKEN

Step 2.4: Build the Docker Image

Still in the gmail-mcp-server folder, run:

docker build -t gmail-mcp-server:latest .

This takes ~2-3 minutes. You'll see a bunch of output. Wait for:

Successfully tagged gmail-mcp-server:latest

✅ Docker image built!

Step 2.5: Register the Server

Create the catalog file for Docker MCP:

macOS/Linux:

mkdir -p ~/.docker/mcp/catalogs
nano ~/.docker/mcp/catalogs/custom.yaml

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.docker\mcp\catalogs"
notepad "$env:USERPROFILE\.docker\mcp\catalogs\custom.yaml"

Paste this into the file:

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  gmail:
    description: "Send, read, and manage Gmail emails with AI"
    title: "Gmail MCP Server"
    type: server
    dateAdded: "2025-01-01T00:00:00Z"
    image: gmail-mcp-server:latest
    ref: ""
    env:
      GMAIL_CLIENT_ID:
        secret: GMAIL_CLIENT_ID
      GMAIL_CLIENT_SECRET:
        secret: GMAIL_CLIENT_SECRET
      GMAIL_REFRESH_TOKEN:
        secret: GMAIL_REFRESH_TOKEN
    tools:
      - name: gmail_list_messages
      - name: gmail_get_message
      - name: gmail_send_message
      - name: gmail_reply_message
      - name: gmail_modify_labels
    metadata:
      category: productivity
      tags:
        - email
        - gmail
        - communication

Save and close (Ctrl+O, Enter, Ctrl+X in nano / File → Save in Notepad)

Step 2.6: Enable the Server

docker mcp server enable gmail

Verify it's enabled:

docker mcp server ls

You should see gmail in the list with status enabled.

✅ Part 2 Complete! Server is installed.

Part 3: Connect to Claude Desktop (5 minutes)

Final step: Tell Claude Desktop to use your Gmail MCP server.

Step 3.1: Find Your Claude Config File

macOS:

open ~/Library/Application\ Support/Claude/

Windows:

explorer "$env:APPDATA\Claude"

You should see a file called claude_desktop_config.json.

Step 3.2: Edit the Config File

Open claude_desktop_config.json in a text editor.

If it's empty or only has {}, replace everything with:

{
  "mcpServers": {
    "docker-mcp": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

If it already has content, just add the "docker-mcp" section inside "mcpServers":

{
  "mcpServers": {
    "docker-mcp": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    },
    "other-server": {
      ...
    }
  }
}

Save the file.

Step 3.3: Restart Claude Desktop

1. Completely quit Claude Desktop (right-click icon → Quit, or Cmd+Q / Alt+F4)
2. Wait 5 seconds
3. Relaunch Claude Desktop

Step 3.4: Verify It's Working

In Claude Desktop, start a new conversation and type:

Can you list my Gmail tools?

Claude should respond showing 5 Gmail tools:

• gmail_list_messages
• gmail_get_message
• gmail_send_message
• gmail_reply_message
• gmail_modify_labels

✅ YOU'RE DONE! 🎉

How to Use It

Now that it's set up, just talk to Claude naturally:

📨 Read Emails

"Show me my unread emails"
"Find all emails from john@company.com this week"
"What did Sarah say in her last email?"

✍️ Draft & Send Emails

"Draft an email to boss@company.com apologizing for being late to the meeting"
"Send an email to client@example.com following up on the proposal"
"Reply to the last email from john@company.com thanking him for the update"

🔍 Search & Organize

"Find all emails with 'invoice' in the subject from last month"
"Star all unread emails from my manager"
"Archive all emails from newsletter@company.com"
"Mark all emails from today as read"

🎯 Smart Workflows

"Read my unread emails, summarize the important ones, and draft replies for each"
"Find all emails with attachments from this week and list them"
"Search for emails about the product launch and create a summary"

The AI will draft, review, and send emails for you. You just approve.

Gmail Search Syntax

The server supports Gmail's powerful search operators:

Combine them:

from:john@company.com is:unread has:attachment after:2024/01/01

Troubleshooting

"Server not showing up in Claude"

Fix:

1. Verify Docker Desktop is running (green icon)
2. Check Docker image exists:

   docker images | grep gmail-mcp-server
   

3. Verify secrets are set:

   docker mcp secret list
   

4. Check server is enabled:

   docker mcp server ls
   

5. Completely quit and restart Claude Desktop (Cmd+Q / Alt+F4, then relaunch)

"Authentication failed" or "Invalid credentials"

Fix:

1. Your refresh token might be expired (they expire after 6 months of inactivity)
2. Go back to Step 1.4 and generate a new refresh token
3. Update the secret:

   docker mcp secret create GMAIL_REFRESH_TOKEN "NEW_REFRESH_TOKEN_HERE" --force
   

4. Restart Claude Desktop

"Permission denied" errors

Fix: Make sure you authorized all 3 scopes when getting the refresh token:

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

Repeat Step 1.4 and ensure all 3 are checked.

"Rate limit exceeded"

Gmail API has limits:

• Sending: ~500 emails per day
• Reading: 250 requests per second

Fix: Wait a few minutes and try again.

"Container won't start"

Fix: Check container logs:

docker logs $(docker ps -a -q --filter ancestor=gmail-mcp-server:latest)

Look for error messages. Common issues:

• Missing secrets → Check docker mcp secret list
• Wrong secret values → Recreate secrets with correct values
• Port conflicts → Restart Docker Desktop

Still stuck?

1. Check Gmail API Status
2. Verify Docker Desktop is updated to latest version
3. Open an issue on GitHub

Security & Privacy

Your data is safe:

✅ Runs locally - Everything runs on YOUR computer ✅ No cloud storage - Your emails never leave your machine ✅ Open source - You can read every line of code ✅ Docker secrets - Credentials stored securely in Docker ✅ You control access - Revoke access anytime in Google Cloud Console

Best practices:

🔒 Never commit credentials - The .gitignore excludes .env and credential files 🔒 Use Docker secrets - Don't hardcode credentials in files 🔒 Revoke when done - Remove OAuth access in Google Account Settings 🔒 Audit regularly - Check Gmail API quotas for unusual activity

What the server CAN do:

• Read your emails
• Send emails from your account
• Modify labels (read/unread, star, archive)
• Search your mailbox

What the server CANNOT do:

• Delete emails permanently
• Change your password
• Access other Google services (Drive, Calendar, etc.)
• Send emails without you seeing them in Claude first

You're always in control. Claude asks permission before sending emails.

Gmail API Limits

Each operation consumes quota units from your daily allowance:

Sending limit: ~500 emails per day for regular Gmail accounts

Monitor usage: Google Cloud Console → APIs & Services → Dashboard

Uninstalling

To completely remove the server:

# Remove Docker secrets
docker mcp secret rm GMAIL_CLIENT_ID
docker mcp secret rm GMAIL_CLIENT_SECRET
docker mcp secret rm GMAIL_REFRESH_TOKEN

# Disable the server
docker mcp server disable gmail

# Remove the Docker image
docker rmi gmail-mcp-server:latest

# Remove from Claude config
# Edit ~/Library/Application Support/Claude/claude_desktop_config.json
# and remove the "docker-mcp" section

Revoke OAuth access:

1. Go to Google Account Permissions
2. Find "Gmail MCP Server"
3. Click "Remove Access"

Technical Details

Tools Provided

1. gmail_list_messages

   • Search and list emails
   • Supports Gmail search operators
   • Returns message IDs, snippets, and metadata

2. gmail_get_message

   • Retrieve full email content
   • Includes headers, body, and thread info
   • Supports HTML and plain text

3. gmail_send_message

   • Send new emails
   • Supports To, Cc, Bcc, Subject, Body
   • HTML and plain text support

4. gmail_reply_message

   • Reply to existing emails
   • Maintains thread context
   • Auto-fills To/Subject from original

5. gmail_modify_labels

   • Mark as read/unread
   • Star/unstar messages
   • Archive messages
   • Add/remove custom labels

Tech Stack

• Runtime: Node.js with TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• Gmail API: googleapis npm package
• Container: Docker
• Gateway: Docker MCP Gateway

API Scopes Used

https://www.googleapis.com/auth/gmail.readonly  # Read emails
https://www.googleapis.com/auth/gmail.modify    # Modify labels
https://www.googleapis.com/auth/gmail.send      # Send emails

Contributing

Found a bug? Want to add a feature?

1. Fork this repository
2. Create a branch: git checkout -b feature/your-feature
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Ideas for contributions:

• Attachment handling (download/upload)
• Draft management
• Calendar integration
• Gmail filters management
• Batch operations
• Analytics dashboard

Credits & Resources

Built with:

• Model Context Protocol - MCP specification
• Gmail API - Google's email API
• Docker MCP Gateway - Docker's MCP runtime
• Anthropic Claude - AI assistant

Inspired by:

• NetworkChuck's Docker MCP Tutorial
• Anthropic's MCP Quickstart

Support

Questions? Issues?

• 📧 Open an issue on GitHub
• 📖 Read the MCP Documentation
• 🐛 Check Gmail API Troubleshooting

Like this project?

• ⭐ Star this repo
• 🐦 Follow me on X: @yourusername
• 💼 Connect on LinkedIn: Your Name

Roadmap

✅ v1.0 (Current)

• Basic email operations (list, read, send, reply)
• Label management
• Gmail search syntax
• Docker deployment

🚧 v1.1 (In Progress)

• Attachment download/upload
• Draft management
• Better error messages
• Usage analytics

🔮 v2.0 (Planned)

• Gmail filters management
• Vacation responder control
• Signature management
• Email templates
• Scheduled sending

Want to help? Check the Contributing section above.

FAQ

Is this safe to use?

Yes. The server runs entirely on your computer, never sends data to third parties, and you control all access via Google Cloud Console.

Will Claude send emails without asking me?

No. Claude will always show you the draft email and ask for confirmation before sending.

Can I use this with GSuite/Google Workspace?

Yes! Works with both personal Gmail and Google Workspace accounts.

Does this cost money?

The server is free. Gmail API is free for most use cases (under daily limits). Docker Desktop is free for personal use.

Can I use multiple Gmail accounts?

Not simultaneously. You'd need to run separate instances with different credentials.

What happens if I hit rate limits?

The server will return an error. Wait a few minutes and try again. For high-volume use, consider applying for higher quotas in Google Cloud Console.

Can I schedule emails?

Not yet. This is planned for v2.0. For now, you can use Gmail's "Schedule Send" feature manually.

Does this work offline?

No. You need internet to access Gmail API.

Can I see the emails Claude sends before they go out?

Yes! Claude always shows you the full email draft and waits for your approval.

Example Workflows

Workflow 1: Daily Email Triage

Prompt:

"Review my unread emails from today. For each:
1. Summarize the key points
2. Suggest if I should reply, archive, or star it
3. Draft a reply if needed

Then show me the summary and ask what I want to do."

Result: AI triages your inbox and prepares responses.

Workflow 2: Follow-up Automation

Prompt:

"Find all emails I sent last week that haven't received a reply.
For each, draft a polite follow-up email."

Result: Never forget to follow up again.

Workflow 3: Newsletter Cleanup

Prompt:

"Find all emails with 'unsubscribe' in the body from the last month.
List the senders. I'll tell you which ones to archive."

Result: Clean inbox, keep what matters.

Workflow 4: Meeting Scheduling

Prompt:

"Find the email thread about the project meeting.
Draft a reply proposing 3 time slots next week: Tuesday 2pm, Wednesday 10am, Thursday 3pm."

Result: Quick meeting coordination.

What's Next?

Now that you have Gmail MCP Server set up:

1. Try it out - Send a test email to yourself
2. Explore workflows - See what Claude can do with your email
3. Give feedback - Open issues or suggest features
4. Share it - Help others escape typo anxiety

Day 2/30 of building in public. 🚀

Let's make email less painful, one AI-powered draft at a time.

Made with ❤️ and caffeine ☕ by [Your Name]

Star this repo if it saved you from an embarrassing typo! ⭐