# 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:

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

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

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

---

### Step 3 — Create a Python Virtual Environment

```powershell
# 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

```powershell
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.**

```powershell
# 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.

```powershell
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:

```json
{
  "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](LICENSE) file for details.