Gmail MCP Server 📬

A local Model Context Protocol (MCP) server that connects AI assistants (like Claude) directly to your Gmail account. It lets an AI read your inbox, save drafts, and send emails — but only when you explicitly approve it.

🤔 What Does This Server Do?

This server acts as a secure bridge between an AI assistant and your Gmail. Instead of giving an AI full access to your email, it exposes exactly 3 controlled tools:

🔐 Why Is It Safe?

• list_recent_emails uses read-only Gmail scope. It cannot modify anything.

• draft_reply calls drafts.create — the Gmail API endpoint for creating drafts. The code does not contain messages.send anywhere. An AI cannot accidentally send an email through this tool.

• send_confirmed_email requires a secret token that only you know. Without it, the request is blocked in Python code before Gmail is ever contacted.

Related MCP server: Gmail MCP Server

✅ Prerequisites

Before starting, make sure you have:

• Python 3.10 or newer — check with python --version

• Node.js — needed to run the MCP Inspector. Download from https://nodejs.org

• A Google account (the Gmail you want to connect)

• A Google Cloud project with the Gmail API enabled (see Step 1 below)

🚀 Setup Guide

Step 1 — Enable Gmail API on Google Cloud (One-Time Setup)

This gives your server permission to talk to Gmail.

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

2. Click "Select a project" → "New Project" → give it any name → Create

3. In the left menu go to APIs & Services → Library

4. Search for "Gmail API" → click it → click Enable

5. Go to APIs & Services → OAuth consent screen

   • Choose External → click Create

   • Fill in an App name (e.g. Gmail MCP) and your email → click Save and Continue through all steps

   • On the Test Users page → click "+ Add Users" → add your Gmail address → Save

6. Go to APIs & Services → Credentials

   • Click "+ Create Credentials" → choose "OAuth 2.0 Client ID"

   • Application type: Desktop app → click Create

   • Click "Download JSON" on the newly created credential

7. Rename the downloaded file to credentials.json and place it in this project folder:

gmail-mcp-server/
└── credentials.json   ← put it here

⚠️ credentials.json is in .gitignore and will never be committed to GitHub. Keep it private.

Step 2 — Clone the Repository

git clone https://github.com/adel-noufal/Gmail-Mcp-Server-Automation.git
cd Gmail-Mcp-Server-Automation

Step 3 — Create a Python Virtual Environment

# Create the virtual environment
python -m venv .venv

# Activate it (Windows PowerShell)
.\.venv\Scripts\Activate.ps1

# If you get a permissions error, run this first:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

On Mac/Linux: source .venv/bin/activate

Step 4 — Install Dependencies

pip install -r requirements.txt

This installs the MCP library, Google API client, and authentication libraries.

Step 5 — Set Your Secret Approval Token

This token is your personal key that allows the send_confirmed_email tool to actually send. Choose any secret string you like.

# Windows PowerShell
$env:MCP_APPROVAL_TOKEN="your_secret_token_here"

On Mac/Linux: export MCP_APPROVAL_TOKEN="your_secret_token_here"

⚠️ You must set this every time you open a new terminal. To make it permanent, add it to your system environment variables.

Step 6 — Run the Server with MCP Inspector

The MCP Inspector is a browser-based tool that lets you test your server visually without needing to connect a full AI assistant.

npx -y @modelcontextprotocol/inspector .venv\Scripts\python server.py

On Mac/Linux: npx -y @modelcontextprotocol/inspector .venv/bin/python server.py

Then open your browser and go to:

http://localhost:5173

Step 7 — Authenticate with Google (First Run Only)

When you run the server for the first time, a browser window will open automatically asking you to log in to Google.

1. Select your Google account

2. You may see a warning "Google hasn't verified this app" — click "Advanced" → "Go to [App Name] (unsafe)"

3. Click Allow on the permissions screen

4. The browser will show "Authentication successful" — you can close it

A token.json file is now saved locally. You will not need to log in again unless you delete this file.

🧪 Testing the Tools

Once the Inspector is open at http://localhost:5173, you'll see all 3 tools listed. Here's how to test each one:

Tool 1 — list_recent_emails

• Click the tool → click Run (no parameters needed)

• You'll see a list of your last 10 inbox emails with subject, sender, and date

Tool 2 — draft_reply

Fill in the parameters:

to:      friend@example.com
subject: Hello from MCP!
body:    This is a test draft created by my Gmail MCP server.

• Click Run

• Open Gmail → go to Drafts → you'll see the email sitting there, unsent ✅

Tool 3 — send_confirmed_email

With a wrong token (to test the security gate):

to:             friend@example.com
subject:        Test
body:           Hello!
approval_token: wrongtoken

• Click Run → you'll get "status": "blocked" ✅ The gate works.

With the correct token (to actually send):

to:             friend@example.com
subject:        Hello from MCP!
body:           This email was sent by my Gmail MCP server!
approval_token: your_secret_token_here

• Click Run → email is sent ✅

⚙️ Connect to Claude or Another AI Assistant

To connect this server to an AI assistant like Claude, add this block to your MCP configuration file:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "C:\\path\\to\\gmail-mcp-server\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\gmail-mcp-server\\server.py"
      ],
      "env": {
        "MCP_APPROVAL_TOKEN": "your_secret_token_here"
      }
    }
  }
}

Replace C:\\path\\to\\gmail-mcp-server with the actual path to your project folder.

📁 Project Structure

gmail-mcp-server/
├── server.py                  # Main MCP server — defines all 3 tools
├── auth.py                    # Handles Google OAuth 2.0 login
├── requirements.txt           # Python dependencies
├── credentials.json.template  # Template showing the credentials.json format
├── .gitignore                 # Excludes credentials.json and token.json from git
├── LICENSE                    # MIT License
└── README.md                  # This file

credentials.json and token.json are never committed — they contain your private Google credentials.

❓ Troubleshooting

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.