@bakhshb/google-mcp-appkey

Google MCP server using app passwords — no OAuth, no expiring tokens. Works with personal Gmail accounts via IMAP (email) + CalDAV (calendar).

Why This Exists

OAuth2 tokens expire. Refresh tokens get invalidated. Re-authorizing every few days is annoying.

This MCP uses your Google app password instead — a static 16-character password that never expires. Set it once, forget it.

Features

Gmail (IMAP + SMTP)

• 📬 List emails with search (unread, from, subject)
• 📖 Read full email by UID
• ✉️ Send emails via SMTP
• 📁 Archive emails
• 🗑️ Trash emails

Calendar (CalDAV)

• 📅 List upcoming events with time range
• ➕ Create events
• ❌ Delete events

Prerequisites

• A personal Google account (Gmail)
• 2-Step Verification enabled on your Google account
• An app password generated from your Google account

Setup

1. Generate an App Password

1. Go to Google App Passwords
2. Sign in with your Google account
3. Under "App passwords", click Create a new app password
4. Name it something like "MCP" or "OpenClaw"
5. Copy the 16-character password (format: xxxx xxxx xxxx xxxx)

2. Install

npm install -g @bakhshb/google-mcp-appkey

Or use directly with npx:

npx @bakhshb/google-mcp-appkey

3. Configure Environment Variables

Set these environment variables:

export GMAIL_USER="[email protected]"
export GMAIL_APP_PASSWORD="xxxxxxxxxxxxxxxxxxxx"  # 16 chars, no spaces

4. Add to Your MCP Client

OpenClaw (~/.openclaw/openclaw.json):

{
  "mcp": {
    "servers": {
      "google-mcp": {
        "command": "npx",
        "args": ["-y", "@bakhshb/google-mcp-appkey"],
        "env": {
          "GMAIL_USER": "${GMAIL_USER}",
          "GMAIL_APP_PASSWORD": "${GMAIL_APP_PASSWORD}"
        }
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "google-mcp": {
      "command": "npx",
      "args": ["-y", "@bakhshb/google-mcp-appkey"],
      "env": {
        "GMAIL_USER": "[email protected]",
        "GMAIL_APP_PASSWORD": "xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "google-mcp": {
      "command": "npx",
      "args": ["-y", "@bakhshb/google-mcp-appkey"],
      "env": {
        "GMAIL_USER": "[email protected]",
        "GMAIL_APP_PASSWORD": "xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Tools

Gmail

| Tool | Description | Parameters | |------|-------------|------------| | gmail_list | List emails | query (optional): is:unread, from:x, subject:x, ALLmaxResults (optional, default: 10) | | gmail_read | Read email body | id: Email UID | | gmail_send | Send email | to: Recipientsubject: Subject linebody: Plain text body | | gmail_archive | Archive email | id: Email UID | | gmail_trash | Move to trash | id: Email UID |

Calendar

| Tool | Description | Parameters | |------|-------------|------------| | calendar_list | List upcoming events | timeMin (optional): ISO 8601 starttimeMax (optional): ISO 8601 endmaxResults (optional, default: 10) | | calendar_create | Create event | summary: Event titlestart: ISO 8601 start timeend: ISO 8601 end timedescription (optional)location (optional) | | calendar_delete | Delete event | eventId: Event UID or .ics filename |

How It Works

┌─────────────┐     IMAP/SMTP      ┌─────────────────┐
│   Gmail     │ ◄────────────────► │                 │
│  (Google)   │                    │  google-mcp-    │
├─────────────┤     CalDAV         │    appkey       │
│  Calendar   │ ◄────────────────► │                 │
│  (Google)   │                    │  (MCP Server)   │
└─────────────┘                    └────────┬────────┘
                                            │ MCP Protocol
                                   ┌────────▼────────┐
                                   │  Your AI Agent  │
                                   │  (OpenClaw,     │
                                   │   Claude, etc.) │
                                   └─────────────────┘

• Gmail → IMAP (imap.gmail.com:993) for reading, SMTP (smtp.gmail.com:465) for sending
• Calendar → CalDAV (https://www.google.com/calendar/dav/) for events
• Auth → Basic auth with app password (no OAuth flow)

App Password vs OAuth

| | App Password (this package) | OAuth2 | |---|---|---| | Setup | Generate password, done | OAuth flow, redirect URLs | | Expires | ❌ Never | ✅ Tokens expire | | Maintenance | None | Re-authorize periodically | | Scope | Gmail + Calendar | Gmail + Calendar + more | | Requirements | Personal Gmail + 2FA | Google Cloud project |

Limitations

• App passwords only work with personal Google accounts (not Workspace without admin setup)
• 2-Step Verification must be enabled
• CalDAV uses Google's legacy endpoint (works, but officially "unsupported")
• No labels, filters, or advanced Gmail features (only IMAP-level operations)

Troubleshooting

"Invalid credentials"

• Verify your app password is correct (16 chars, no spaces)
• Make sure 2-Step Verification is enabled on your Google account

"Connection refused"

• Check your internet connection
• Google might be blocking — try from a different network

Calendar returns no events

• Make sure you have events in your primary calendar
• Check the time range (default is now → +7 days)

Development

git clone https://gitlab.labby.space/bakhshb/google-mcp-appkey.git
cd google-mcp-appkey
npm install
[email protected] GMAIL_APP_PASSWORD=xxxx node index.mjs

License

MIT

Author

Baraa Bakhsh (GitHub | GitLab)