# Gmail MCP Local Server

A local MCP (Model Context Protocol) server that gives Claude the ability to send emails, manage drafts, and search Gmail — capabilities missing from Anthropic's built-in Gmail connector.

---

## What is MCP and how does this work?

MCP is a protocol that lets Claude call real-world tools. When you register an MCP server, Claude Desktop launches it as a background subprocess and routes tool calls to it over stdin/stdout.

```
You talk to Claude
       │
       ▼
Claude decides which tool to use
       │
       ▼
MCP server executes the action
(send email, search messages, etc.)
       │
       ▼
Real world effect happens
```

You never run this script manually. Claude Desktop starts and stops it automatically.

---

## Tools

| Tool | Description |
|------|-------------|
| `gmail_send_email` | Compose and immediately send an email |
| `gmail_send_draft` | Send an existing draft by its draft ID |
| `gmail_create_draft` | Save a composed email as a draft without sending |
| `gmail_list_drafts` | List saved drafts with subject and recipient info |
| `gmail_search_messages` | Search messages using Gmail query syntax |
| `gmail_read_message` | Read the full decoded body of a message |

---

## Setup

### 1. Install dependencies

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 2. Google Cloud setup

You need a `credentials.json` from Google Cloud Console. This is your app's identity card with Google.

1. Go to [console.cloud.google.com](https://console.cloud.google.com)
2. Create a project
3. Go to **APIs & Services → Library** → enable **Gmail API**
4. Go to **APIs & Services → OAuth consent screen**
   - Choose **External** → fill in app name and your email
   - Under **Test users**, add your Gmail address
5. Go to **APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID**
   - Application type: **Desktop app**
   - Download the JSON and save it as `credentials.json` in this folder

Copy `.env.example` to `.env` and fill in your values (these match what's inside `credentials.json`):

```bash
cp .env.example .env
```

### 3. Register with Claude Desktop

Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "/FULL/PATH/TO/gmail_mcp/venv/bin/python3",
      "args": ["/FULL/PATH/TO/gmail_mcp/gmail_mcp.py"]
    }
  }
}
```

Restart Claude Desktop.

---

## First-run OAuth (one time only)

The first time Claude uses a Gmail tool, a browser window will open asking you to sign in with Google and grant access. After you approve:

- A `token.json` file is saved in this folder
- All future runs reuse this token silently
- The token auto-refreshes when it expires — no action needed

**Why the test user step matters:** Google blocks OAuth for apps in "Testing" mode unless your email is explicitly listed as a test user. That's the `403: access_denied` error if skipped.

---

## How Claude Desktop manages the server

```
Claude Desktop starts
       │
       │  spawns subprocess automatically
       ▼
gmail_mcp.py runs in background
       │
       │  reads token.json for auth
       ▼
Gmail API (Google's servers)
```

- No manual start needed — Claude Desktop handles it
- The server only runs while Claude Desktop is open
- If you use a scheduler, it only fires while Claude Desktop is running on your machine

---

## Security

- `token.json` contains a live OAuth refresh token — full Gmail access. Keep it private.
- `credentials.json` contains your app's client secret. Keep it private.
- Neither file is committed to git (covered by `.gitignore`)
- If your token is compromised, revoke it at [myaccount.google.com/permissions](https://myaccount.google.com/permissions) and delete `token.json` to force re-auth

---

## What else can you build with MCP?

MCP works with any API. Some ideas:

- **Google Calendar** — create and read events
- **Notion** — read/write pages and databases
- **Slack** — send messages, read channels
- **GitHub** — open issues, create PRs
- **Google Sheets** — read/write spreadsheet data
- **SMS / WhatsApp** — send messages via Twilio
- **Local filesystem** — read/write files in specific folders
- **Databases** — query SQLite or Postgres

The pattern is always the same: write a Python file with `@mcp.tool()` functions, register it in `claude_desktop_config.json`, and Claude can act in the real world through it.