Gmail-Mcp-Server-Automation

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. It exposes controlled tools for inbox reading, drafting, sending, and AI generation:

Tool	What It Does	Can It Send Email?
list_recent_emails	Reads the last 10 emails in your inbox (subject, sender, date only — no body)	❌ No
draft_reply	Creates a draft in your Gmail Drafts folder	❌ No — structurally impossible
send_confirmed_email	Sends an email via Gmail	✅ Yes — but only if you provide a secret token
smart_email_assistant	All-in-One: Auto-generates or uses typed body, then saves as draft or sends	⚠️ Only if action="send" AND token provided

🔐 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.

---

✅ 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

Problem	Solution
credentials.json not found	Make sure you downloaded and renamed the file from Google Cloud Console and placed it in the project root
Execution policy error on .Activate.ps1	Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Browser doesn't open for Google login	Run python auth.py manually to trigger the login flow
MCP_APPROVAL_TOKEN not set error	You forgot Step 5 — set the environment variable before starting the server
Inspector shows no tools	Make sure you're running the command from inside the project folder with the venv activated

---

📄 License

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