Content
# claude-2-mail
Local MCP server for Gmail + Google Calendar. Lets your AI agent read/send email and manage your calendar — runs locally via stdio.
## Tools
| Tool | What it does |
|------|-------------|
| `mail_list` | List recent emails (folder, count, unread filter) |
| `mail_read` | Read full email by UID |
| `mail_search` | Search by sender, subject, body, date range |
| `mail_draft` | Draft a reply or new email |
| `mail_send` | Send an approved email |
| `mail_auto_reply` | Auto-reply to whitelisted senders |
| `calendar_list` | List upcoming events |
| `calendar_create` | Create a new event |
| `calendar_update` | Update or delete an event |
## Prerequisites
- Python 3.10+
- A Google account
- An MCP-compatible client (Claude Code, Cursor, etc.)
## Setup
### Auth Pipeline (Overview)
There are **two separate auth systems**:
| System | Used for | How it works |
|--------|----------|-------------|
| **Gmail App Password** | IMAP (read) + SMTP (send) | 16-char password from Google Account settings |
| **Google OAuth2** | Calendar API | Browser-based consent flow, saves a token file |
You need both. App Password for email, OAuth2 for calendar.
### 1. Install Dependencies
```bash
pip install mcp google-api-python-client google-auth-httplib2 google-auth-oauthlib
```
### 2. Create a Gmail App Password (for Email)
Gmail uses IMAP/SMTP with an App Password — NOT your real Google password.
**Steps:**
1. Go to [Google Account Security](https://myaccount.google.com/security)
2. Enable **2-Step Verification** (required — App Passwords won't work without it)
3. Go to [App Passwords](https://myaccount.google.com/apppasswords)
4. Select app: **Mail**, device: **Other (Custom name)** → type "claude-2-mail"
5. Click **Generate** → copy the 16-character password (e.g. `abcd efgh ijkl mnop`)
**Why:** Google blocks "less secure apps". App Passwords are per-app tokens that bypass this.
### 3. Create a Google Cloud Project (for Calendar)
Calendar needs OAuth2. This is a multi-step process — follow in order:
**Step A — Create project + enable API:**
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click **Select a project** → **New Project** → name it → **Create**
3. Select your new project
4. Go to **APIs & Services → Library**
5. Search **"Google Calendar API"** → click it → **Enable**
**Step B — Configure OAuth consent screen:**
1. Go to **APIs & Services → OAuth consent screen**
2. User type: **External** → **Create**
3. Fill in: App name, User support email, Developer contact email
4. **Save and Continue** through scopes (add nothing) → **Back to Dashboard**
5. Under **Test users** → **Add users** → add your own email address
**Why Test users:** Until your app is published, only test users can authorize it. Without this step, OAuth will fail with "access_blocked".
**Step C — Create OAuth credentials:**
1. Go to **APIs & Services → Credentials**
2. **Create Credentials** → **OAuth client ID**
3. Application type: **Desktop app** → name it → **Create**
4. Click **Download JSON** → save the file
**Why Desktop app:** MCP servers run locally. "Desktop app" type doesn't need a redirect URI — it uses localhost callback.
### 4. Configure
```bash
mkdir -p ~/.config/claude-2-mail
cp config/config.template.json ~/.config/claude-2-mail/config.json
cp config/.secrets.template ~/.config/claude-2-mail/.secrets
cp config/credentials.json.template ~/.config/claude-2-mail/credentials.json
```
Edit each file:
**`~/.config/claude-2-mail/config.json`** — your email, display name, settings.
**`~/.config/claude-2-mail/.secrets`** — your App Password:
```
export GMAIL_APP_PASSWORD="abcd efgh ijkl mnop"
```
**`~/.config/claude-2-mail/credentials.json`** — paste the downloaded OAuth JSON.
Lock permissions:
```bash
chmod 600 ~/.config/claude-2-mail/config.json
chmod 600 ~/.config/claude-2-mail/.secrets
chmod 600 ~/.config/claude-2-mail/credentials.json
```
### 5. Source the Secrets
Add to `~/.bashrc` or `~/.zshrc`:
```bash
[ -f ~/.config/claude-2-mail/.secrets ] && source ~/.config/claude-2-mail/.secrets
```
Reload: `source ~/.bashrc`
### 6. Register in Your MCP Client
**Claude Code** (`~/.mcp.json`):
```json
{
"mcpServers": {
"gmail-calendar": {
"command": "python",
"args": ["/path/to/claude-2-mail/gmail_calendar_mcp.py"],
"env": {
"GMAIL_MAIL_CONFIG": "/home/YOUR_USER/.config/claude-2-mail/config.json"
}
}
}
}
```
### 7. First Run
First Calendar use opens a browser for OAuth approval. One-time — token saves for future.
## Troubleshooting
| Problem | Fix |
|---------|-----|
| `AUTHENTICATIONFAILED` (IMAP) | Regenerate App Password. 2FA must be on. |
| `invalid_client` (OAuth) | Check credentials.json is Desktop app type. |
| `access_blocked` (OAuth) | Add your email as Test user in OAuth consent screen. |
| `Token expired` | Delete `calendar_token.json`, re-auth. |
| `Config not found` | Check `GMAIL_MAIL_CONFIG` env var path. |
| `CredentialsWithRegionalAccessBoundary.refresh() missing argument` | Update google-auth: `pip install --upgrade google-auth` |
| Missing pip libs | `pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib` |
## Testing
```bash
pip install -e ".[dev]"
pytest tests/ -v
```
## Security
- App Password in `.secrets` (chmod 600), NOT in config.json or shell rc
- OAuth tokens stored chmod 600
- Logging redacts emails/tokens/passwords at INFO level
- IMAP input escaped to prevent injection
- Narrow OAuth scopes only
## License
MIT.
