{"_id":"@bakhshb/google-mcp","name":"@bakhshb/google-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@bakhshb/google-mcp","version":"1.0.0","description":"Minimal Google Gmail + Calendar MCP server","main":"dist/index.js","type":"module","bin":{"google-mcp":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"keywords":["mcp","gmail","google-calendar","google","ai","model-context-protocol"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/bakhshb/google-mcp.git"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","googleapis":"^144.0.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0"},"_id":"@bakhshb/google-mcp@1.0.0","gitHead":"f461cb76f00a0d1701b2af3dbf9ba41d71e9ba05","types":"./dist/index.d.ts","bugs":{"url":"https://github.com/bakhshb/google-mcp/issues"},"homepage":"https://github.com/bakhshb/google-mcp#readme","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-4PIhqMc8QulXdB2+q+CPPYqeZc35UROA1LCco5WId8HE7S3tj6eFJS2miMljR0OZda7XsEpIUUw9ZSM0UzhrXg==","shasum":"3334a8eb8c4675a439a78bffd42cac1aec717ec4","tarball":"https://registry.npmjs.org/@bakhshb/google-mcp/-/google-mcp-1.0.0.tgz","fileCount":8,"unpackedSize":45300,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCCxQoVtOdmeqi49RJWx/b88AkH4U3lOYEICXBB3naRrQIgLw+h3GlVPc8h7A3t7e+7ypmCizu4u5wHY2wqCoRyKIc="}]},"_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_1.0.0_1775673416520_0.8869870710845713"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-08T18:36:56.413Z","1.0.0":"2026-04-08T18:36:56.692Z","modified":"2026-04-08T18:36:56.918Z"},"maintainers":[{"name":"bakhshb","email":"bakhshb@gmail.com"}],"description":"Minimal Google Gmail + Calendar MCP server","homepage":"https://github.com/bakhshb/google-mcp#readme","keywords":["mcp","gmail","google-calendar","google","ai","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/bakhshb/google-mcp.git"},"bugs":{"url":"https://github.com/bakhshb/google-mcp/issues"},"license":"MIT","readme":"# Google MCP Server\n\nMinimal MCP server for Gmail + Google Calendar. 10 tools, 2 dependencies, zero bloat.\n\nBuilt to replace heavy integrations (like Arcade's 7,000+ tool cache) with exactly what you need: read email, send email, manage your calendar.\n\n## Tools\n\n### Gmail (5)\n\n| Tool | Description |\n|------|-------------|\n| `gmail_list` | List recent emails or search Gmail. Supports standard Gmail search queries (`from:`, `subject:`, `label:`, etc.) |\n| `gmail_read` | Read a full email by ID (headers + body) |\n| `gmail_send` | Send an email with optional CC and reply threading |\n| `gmail_label` | Add or remove labels from an email |\n| `gmail_archive` | Archive or trash an email |\n\n### Calendar (5)\n\n| Tool | Description |\n|------|-------------|\n| `calendar_list` | List upcoming events (defaults to next 7 days) |\n| `calendar_get` | Get details of a specific event |\n| `calendar_create` | Create an event with title, time, location, description, and attendees |\n| `calendar_delete` | Delete an event |\n| `calendar_freebusy` | Find free/busy slots in a time range |\n\n## Prerequisites\n\n- **Node.js** 18+ (ES2022)\n- **Google Cloud project** with Gmail API and Google Calendar API enabled\n- **OAuth 2.0 credentials** (Desktop app type)\n\n## Setup\n\n### 1. Google Cloud Project\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com)\n2. Create a new project (or select an existing one)\n3. Enable **Gmail API** and **Google Calendar API**:\n   - Navigate to **APIs & Services → Library**\n   - Search for each API and click **Enable**\n4. Create OAuth credentials:\n   - Navigate to **APIs & Services → Credentials**\n   - Click **Create Credentials → OAuth client ID**\n   - Application type: **Desktop app**\n   - Add authorized redirect URI: `http://localhost:3000/callback`\n   - Copy the **Client ID** and **Client Secret**\n\n### 2. Install & Build\n\n```bash\ngit clone https://github.com/bakhshb/google-mcp.git\ncd google-mcp\nnpm install\nnpm run build\n```\n\n### 3. Environment Variables\n\nSet these environment variables (or configure them in your MCP client):\n\n| Variable | Description |\n|----------|-------------|\n| `GOOGLE_CLIENT_ID` | OAuth 2.0 Client ID from Google Cloud |\n| `GOOGLE_CLIENT_SECRET` | OAuth 2.0 Client Secret from Google Cloud |\n\n### 4. First Run — Authorize\n\nOn first launch, the server detects missing auth tokens and starts an OAuth flow:\n\n1. A URL is printed to stderr — open it in a browser\n2. Authorize with your Google account\n3. The callback is caught on `localhost:3000`\n4. Tokens are saved to `~/.google-mcp/auth.json` (chmod 600)\n\nSubsequent launches skip this step — the saved refresh token handles everything.\n\n### 5. Configure Your AI Agent\n\n#### OpenClaw\n\nAdd to `openclaw.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/google-mcp/dist/index.js\"],\n      \"env\": {\n        \"GOOGLE_CLIENT_ID\": \"${GOOGLE_CLIENT_ID}\",\n        \"GOOGLE_CLIENT_SECRET\": \"${GOOGLE_CLIENT_SECRET}\"\n      }\n    }\n  }\n}\n```\n\nStore the actual values in `.openclaw/.env`:\n\n```\nGOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=your-client-secret\n```\n\n#### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/google-mcp/dist/index.js\"],\n      \"env\": {\n        \"GOOGLE_CLIENT_ID\": \"your-client-id.apps.googleusercontent.com\",\n        \"GOOGLE_CLIENT_SECRET\": \"your-client-secret\"\n      }\n    }\n  }\n}\n```\n\n#### Any MCP Client\n\nThe server communicates over stdio and follows the [Model Context Protocol](https://modelcontextprotocol.io/) spec. Point your client's MCP config at:\n\n```\nnode /path/to/google-mcp/dist/index.js\n```\n\nWith env vars `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.\n\n## Architecture\n\n```\nAI Agent ← stdio → MCP Server (TypeScript)\n                        │\n                   Google OAuth2 (refresh tokens)\n                        │\n                   googleapis (Gmail + Calendar)\n```\n\n- **Transport:** stdio (standard MCP)\n- **Auth:** OAuth2 with offline access + auto-refresh\n- **Token storage:** `~/.google-mcp/auth.json` (chmod 600)\n- **Rate limit handling:** exponential backoff, max 3 retries on 429\n- **Token refresh:** automatic via google-auth-library event listener\n\n## OAuth Scopes\n\n```\nhttps://www.googleapis.com/auth/gmail.readonly\nhttps://www.googleapis.com/auth/gmail.modify\nhttps://www.googleapis.com/auth/gmail.compose\nhttps://www.googleapis.com/auth/calendar.readonly\nhttps://www.googleapis.com/auth/calendar\n```\n\n## File Structure\n\n```\ngoogle-mcp/\n├── src/\n│   ├── index.ts    — MCP server entry + all 10 tools\n│   └── auth.ts     — OAuth2 flow + token management\n├── dist/           — compiled output\n├── package.json\n├── tsconfig.json\n├── DESIGN.md\n└── README.md\n```\n\n## Security\n\n- Token file saved with chmod 600\n- No credentials in logs or error messages\n- No email content leaked in errors\n- Only 2 runtime dependencies: `@modelcontextprotocol/sdk` + `googleapis`\n- OAuth tokens never sent to any third party\n\n## Development\n\n```bash\n# Build\nnpm run build\n\n# The server runs on stdio — test it directly:\nGOOGLE_CLIENT_ID=xxx GOOGLE_CLIENT_SECRET=xxx node dist/index.js\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-988aa0365f5ba1f10222d295214d2552"}