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

Related MCP server: mcp-gsuite

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:

You need both. App Password for email, OAuth2 for calendar.

1. Install Dependencies

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

2. Enable 2-Step Verification (required — App Passwords won't work without it)

3. Go to App Passwords

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

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

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:

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:

[ -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):

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

Testing

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.