{"_id":"@bakhshb/google-mcp-appkey","_rev":"2-f51b73b577864d0cf3b087a90a1f528a","name":"@bakhshb/google-mcp-appkey","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@bakhshb/google-mcp-appkey","version":"1.0.0","keywords":["google","mcp","gmail","calendar","imap","caldav","app-password","no-oauth","ai","agent"],"author":{"name":"Baraa Bakhsh"},"license":"MIT","_id":"@bakhshb/google-mcp-appkey@1.0.0","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"bin":{"google-mcp-appkey":"index.mjs"},"dist":{"shasum":"44acd3dfc4f06577f3a0f464a780fcf158681b2b","tarball":"https://registry.npmjs.org/@bakhshb/google-mcp-appkey/-/google-mcp-appkey-1.0.0.tgz","fileCount":4,"integrity":"sha512-w3ZTUoUk7w14Z/XarsdzVszMc6aV7UpIdQsSY2hEO2suLcZGXXX7YaHkRGtbqMbe7XY09e1le1/C5UEdcI2z/A==","signatures":[{"sig":"MEYCIQCfMdCPHkVwdnBD8Zt37l/HMIj+gJ+JPErhl2QdDMIg7AIhAItiX2fRLIWCg2DMimywhCoqyRMRprPngMT5hLfc1skC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":21895},"main":"index.mjs","type":"module","gitHead":"b5a8e28c6a47fd498cc5bf9f1f4ed31943111029","scripts":{"start":"node index.mjs"},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"repository":{"url":"https://gitlab.labby.space/bakhshb/google-mcp-appkey.git","type":"git"},"_npmVersion":"10.9.7","description":"Google MCP server using app passwords (IMAP + CalDAV) — no OAuth, no expiring tokens","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.24.4","ical.js":"^1.5.0","imapflow":"^1.0.186","nodemailer":"^6.10.1","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/google-mcp-appkey_1.0.0_1777149737393_0.8655043736798489","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bakhshb/google-mcp-appkey","version":"1.0.1","description":"Google MCP server using app passwords (IMAP + CalDAV) — no OAuth, no expiring tokens","type":"module","main":"index.mjs","bin":{"google-mcp-appkey":"index.mjs"},"scripts":{"start":"node index.mjs"},"keywords":["google","mcp","gmail","calendar","imap","caldav","app-password","no-oauth","ai","agent"],"author":{"name":"Baraa Bakhsh"},"license":"MIT","repository":{"type":"git","url":"https://gitlab.labby.space/bakhshb/google-mcp-appkey.git"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","ical.js":"^1.5.0","imapflow":"^1.0.186","nodemailer":"^6.10.1","zod":"^3.24.4"},"_id":"@bakhshb/google-mcp-appkey@1.0.1","gitHead":"fd8cc57d51ab3203f28f4dbd6b54246195881a6c","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-AFXbiMZQCWWSUiet6/pnUgC+xtolNrrAWgdNdBJrw63mWgBNJLK9+cqVL77KUuJOGeTc/lg1+2hORlSzB6kBJQ==","shasum":"e94718dbfe80793f0677e90a5bb4793a7715aec1","tarball":"https://registry.npmjs.org/@bakhshb/google-mcp-appkey/-/google-mcp-appkey-1.0.1.tgz","fileCount":4,"unpackedSize":22357,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGeuztFBG4mVDItCdcDW3iIaCqOLGmh7qUqCb7F3IQCeAiEApL1xj/gOb9u40eFlIiQHKF+H40MN36soHLFRj3NJV3U="}]},"_npmUser":{"name":"bakhshb","email":"bakhshb@gmail.com"},"directories":{},"maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/google-mcp-appkey_1.0.1_1777151320979_0.899880218749717"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-25T20:42:17.302Z","modified":"2026-04-25T21:08:41.244Z","1.0.0":"2026-04-25T20:42:17.546Z","1.0.1":"2026-04-25T21:08:41.122Z"},"author":{"name":"Baraa Bakhsh"},"license":"MIT","keywords":["google","mcp","gmail","calendar","imap","caldav","app-password","no-oauth","ai","agent"],"repository":{"type":"git","url":"https://gitlab.labby.space/bakhshb/google-mcp-appkey.git"},"description":"Google MCP server using app passwords (IMAP + CalDAV) — no OAuth, no expiring tokens","maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"readme":"# @bakhshb/google-mcp-appkey\n\n> Google MCP server using **app passwords** — no OAuth, no expiring tokens.\n> Works with personal Gmail accounts via **IMAP** (email) + **CalDAV** (calendar).\n\n## Why This Exists\n\nOAuth2 tokens expire. Refresh tokens get invalidated. Re-authorizing every few days is annoying.\n\nThis MCP uses your Google **app password** instead — a static 16-character password that **never expires**. Set it once, forget it.\n\n## Features\n\n**Gmail (IMAP + SMTP)**\n- 📬 List emails with search (unread, from, subject)\n- 📖 Read full email by UID\n- ✉️ Send emails via SMTP\n- 📁 Archive emails\n- 🗑️ Trash emails\n\n**Calendar (CalDAV)**\n- 📅 List upcoming events with time range\n- ➕ Create events\n- ❌ Delete events\n\n## Prerequisites\n\n- A **personal Google account** (Gmail)\n- 2-Step Verification enabled on your Google account\n- An **app password** generated from your Google account\n\n## Setup\n\n### 1. Generate an App Password\n\n1. Go to [Google App Passwords](https://myaccount.google.com/apppasswords)\n2. Sign in with your Google account\n3. Under \"App passwords\", click **Create a new app password**\n4. Name it something like \"MCP\" or \"OpenClaw\"\n5. Copy the 16-character password (format: `xxxx xxxx xxxx xxxx`)\n\n### 2. Install\n\n```bash\nnpm install -g @bakhshb/google-mcp-appkey\n```\n\nOr use directly with `npx`:\n\n```bash\nnpx @bakhshb/google-mcp-appkey\n```\n\n### 3. Configure Environment Variables\n\nSet these environment variables:\n\n```bash\nexport GMAIL_USER=\"youremail@gmail.com\"\nexport GMAIL_APP_PASSWORD=\"xxxxxxxxxxxxxxxxxxxx\"  # 16 chars, no spaces\n```\n\n### 4. Add to Your MCP Client\n\n**OpenClaw** (`~/.openclaw/openclaw.json`):\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"google-mcp\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"@bakhshb/google-mcp-appkey\"],\n        \"env\": {\n          \"GMAIL_USER\": \"${GMAIL_USER}\",\n          \"GMAIL_APP_PASSWORD\": \"${GMAIL_APP_PASSWORD}\"\n        }\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"google-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bakhshb/google-mcp-appkey\"],\n      \"env\": {\n        \"GMAIL_USER\": \"youremail@gmail.com\",\n        \"GMAIL_APP_PASSWORD\": \"xxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n**Cursor** (`.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"google-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bakhshb/google-mcp-appkey\"],\n      \"env\": {\n        \"GMAIL_USER\": \"youremail@gmail.com\",\n        \"GMAIL_APP_PASSWORD\": \"xxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n## Tools\n\n### Gmail\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `gmail_list` | List emails | `query` (optional): `is:unread`, `from:x`, `subject:x`, `ALL`<br>`maxResults` (optional, default: 10) |\n| `gmail_read` | Read email body | `id`: Email UID |\n| `gmail_send` | Send email | `to`: Recipient<br>`subject`: Subject line<br>`body`: Plain text body |\n| `gmail_archive` | Archive email | `id`: Email UID |\n| `gmail_trash` | Move to trash | `id`: Email UID |\n\n### Calendar\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `calendar_list` | List upcoming events | `timeMin` (optional): ISO 8601 start<br>`timeMax` (optional): ISO 8601 end<br>`maxResults` (optional, default: 10) |\n| `calendar_create` | Create event | `summary`: Event title<br>`start`: ISO 8601 start time<br>`end`: ISO 8601 end time<br>`description` (optional)<br>`location` (optional) |\n| `calendar_delete` | Delete event | `eventId`: Event UID or .ics filename |\n\n## How It Works\n\n```\n┌─────────────┐     IMAP/SMTP      ┌─────────────────┐\n│   Gmail     │ ◄────────────────► │                 │\n│  (Google)   │                    │  google-mcp-    │\n├─────────────┤     CalDAV         │    appkey       │\n│  Calendar   │ ◄────────────────► │                 │\n│  (Google)   │                    │  (MCP Server)   │\n└─────────────┘                    └────────┬────────┘\n                                            │ MCP Protocol\n                                   ┌────────▼────────┐\n                                   │  Your AI Agent  │\n                                   │  (OpenClaw,     │\n                                   │   Claude, etc.) │\n                                   └─────────────────┘\n```\n\n- **Gmail** → IMAP (`imap.gmail.com:993`) for reading, SMTP (`smtp.gmail.com:465`) for sending\n- **Calendar** → CalDAV (`https://www.google.com/calendar/dav/`) for events\n- **Auth** → Basic auth with app password (no OAuth flow)\n\n## App Password vs OAuth\n\n| | App Password (this package) | OAuth2 |\n|---|---|---|\n| **Setup** | Generate password, done | OAuth flow, redirect URLs |\n| **Expires** | ❌ Never | ✅ Tokens expire |\n| **Maintenance** | None | Re-authorize periodically |\n| **Scope** | Gmail + Calendar | Gmail + Calendar + more |\n| **Requirements** | Personal Gmail + 2FA | Google Cloud project |\n\n## Limitations\n\n- App passwords only work with **personal** Google accounts (not Workspace without admin setup)\n- 2-Step Verification must be enabled\n- CalDAV uses Google's legacy endpoint (works, but officially \"unsupported\")\n- No labels, filters, or advanced Gmail features (only IMAP-level operations)\n\n## Troubleshooting\n\n**\"Invalid credentials\"**\n- Verify your app password is correct (16 chars, no spaces)\n- Make sure 2-Step Verification is enabled on your Google account\n\n**\"Connection refused\"**\n- Check your internet connection\n- Google might be blocking — try from a different network\n\n**Calendar returns no events**\n- Make sure you have events in your primary calendar\n- Check the time range (default is now → +7 days)\n\n## Development\n\n```bash\ngit clone https://gitlab.labby.space/bakhshb/google-mcp-appkey.git\ncd google-mcp-appkey\nnpm install\nGMAIL_USER=you@gmail.com GMAIL_APP_PASSWORD=xxxx node index.mjs\n```\n\n## License\n\nMIT\n\n## Author\n\n**Baraa Bakhsh** ([GitHub](https://github.com/bakhshb) | [GitLab](https://gitlab.labby.space/bakhshb))\n","readmeFilename":"README.md"}