{"id":48102768,"url":"https://github.com/navbuildz/gmail-mcp-server","last_synced_at":"2026-04-08T19:00:27.279Z","repository":{"id":348784984,"uuid":"1199866252","full_name":"navbuildz/gmail-mcp-server","owner":"navbuildz","description":"Open-source Gmail MCP server. Multi-account, read, write, archive, label, auto-unsubscribe. Works with Claude, OpenClaw, Cursor, Windsurf, Cline, and any MCP-compatible AI agent or assistant.","archived":false,"fork":false,"pushed_at":"2026-04-03T01:54:08.000Z","size":257,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-07T18:02:41.842Z","etag":null,"topics":["ai-agent","ai-tools","claude","cline","cursor","email","email-automation","gmail","gmail-api","mcp","mcp-server","model-context-protocol","nodejs","oauth2","typescript","windsurf"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/navbuildz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T19:43:26.000Z","updated_at":"2026-04-07T17:41:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/navbuildz/gmail-mcp-server","commit_stats":null,"previous_names":["navbuildz/gmail-mcp-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/navbuildz/gmail-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbuildz%2Fgmail-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbuildz%2Fgmail-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbuildz%2Fgmail-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbuildz%2Fgmail-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/navbuildz","download_url":"https://codeload.github.com/navbuildz/gmail-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbuildz%2Fgmail-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31569400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-tools","claude","cline","cursor","email","email-automation","gmail","gmail-api","mcp","mcp-server","model-context-protocol","nodejs","oauth2","typescript","windsurf"],"created_at":"2026-04-04T15:45:55.054Z","updated_at":"2026-04-08T19:00:27.253Z","avatar_url":"https://github.com/navbuildz.png","language":"TypeScript","readme":"# Gmail MCP Server\n\n### Multi-Account Gmail for AI Agents \u0026 Assistants\n\nAn open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI agents and assistants full read and write access to Gmail. Connect multiple Gmail accounts, search emails, archive, label, and auto-unsubscribe. All through one server.\n\n![Gmail MCP Server Banner](banner.png)\n\nWorks with **Claude**, **OpenClaw**, **Cursor**, **Windsurf**, **Cline**, **Continue**, and any MCP-compatible client.\n\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template?template=https://github.com/navbuildz/gmail-mcp-server)\n\n---\n\n## Why This Exists\n\nMost AI tools ship with a Gmail integration that can only read emails from a single account. No archiving. No labeling. No unsubscribing. And if you use multiple Gmail accounts? You're out of luck.\n\nThis MCP server fixes that. One server, all your accounts, full read and write access.\n\n## Gmail MCP Server vs Built-in Connectors\n\n| Feature | Built-in Gmail (Claude) | Gmail MCP Server |\n|---|---|---|\n| Read emails | Yes | Yes |\n| Write / modify emails | No | **Yes** |\n| Multiple Gmail accounts | No | **Yes** |\n| Archive emails | No | **Yes** |\n| Apply labels | No | **Yes** |\n| Auto-unsubscribe | No | **Yes** |\n| Works with OpenClaw | No | **Yes** |\n| Works with Cursor | No | **Yes** |\n| Works with Windsurf | No | **Yes** |\n| Works with Cline | No | **Yes** |\n| Open source | No | **Yes** |\n\n---\n\n## What is an MCP Server?\n\n[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI agents and assistants connect to external tools and data sources. An MCP server exposes tools that any compatible client can call. Think of it as a plugin system for AI.\n\nThis Gmail MCP server turns any MCP-compatible AI client into a full-featured email agent.\n\n---\n\n## Gmail MCP Server Features\n\n- **Multi-account support.** Connect multiple Gmail accounts and switch between them, or query all at once.\n- **Full read and write access.** Not just reading emails. Archive, label, modify, and unsubscribe.\n- **Gmail search syntax.** Use Gmail's query language: `is:unread`, `from:`, `newer_than:7d`, `has:attachment`, and more.\n- **Auto-unsubscribe.** Finds and triggers unsubscribe links automatically. Supports List-Unsubscribe headers, mailto links, and body link scanning.\n- **Batch operations.** Fetch batches of emails for AI-powered triage and bulk actions.\n- **Secure by design.** OAuth 2.0 authentication, AES-256-GCM encrypted token storage, minimal Gmail scopes.\n- **Deploy anywhere.** Railway, Docker, or your own server.\n\n---\n\n## Available Tools\n\n| Tool | Description |\n|---|---|\n| `list_accounts` | List all connected Gmail accounts |\n| `list_emails` | Search and list emails using Gmail query syntax. Supports `account=\"all\"` |\n| `get_email` | Get full email content, headers, and parsed unsubscribe links |\n| `archive_email` | Archive an email by removing it from the inbox |\n| `apply_label` | Apply a label to an email. Creates the label if it doesn't exist |\n| `unsubscribe_email` | Auto-unsubscribe from mailing lists and newsletters |\n| `batch_process` | Fetch a batch of emails for triage. Supports `account=\"all\"` |\n\n---\n\n## Setup Guide: Deploy in 5 Minutes\n\n### Prerequisites\n\n1. A [Google Cloud](https://console.cloud.google.com) project with the **Gmail API** enabled\n2. OAuth 2.0 credentials (Web application type)\n3. A hosting platform ([Railway](https://railway.app), your own server, or Docker)\n\n### Step 1: Google Cloud Setup\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com) and create a new project\n2. Enable the **Gmail API** (APIs \u0026 Services → Library → search \"Gmail API\" → Enable)\n3. Configure the **OAuth consent screen**:\n   - User type: External\n   - Add scopes: `gmail.readonly`, `gmail.modify`\n   - Add your Gmail addresses as test users\n4. Create **OAuth credentials**:\n   - APIs \u0026 Services → Credentials → Create Credentials → OAuth client ID\n   - Application type: Web application\n   - Authorized redirect URI: `https://your-server-url/oauth/callback`\n   - Save the **Client ID** and **Client Secret**\n\n### Step 2: Deploy\n\n#### Option A: Deploy to Railway (Recommended)\n\n1. Click the Deploy button above, or create a new project on [Railway](https://railway.app) connected to this repo\n2. Add these environment variables:\n\n| Variable | Value |\n|---|---|\n| `GOOGLE_CLIENT_ID` | Your OAuth Client ID |\n| `GOOGLE_CLIENT_SECRET` | Your OAuth Client Secret |\n| `ENCRYPTION_KEY` | Any random string (32+ characters) |\n| `ADMIN_PASSWORD` | Password for the setup page |\n| `SERVER_URL` | Your Railway app URL (e.g., `https://your-app.railway.app`) |\n| `PORT` | `3000` |\n\n3. Generate a domain in Railway (Service → Settings → Networking → Generate Domain)\n4. Update `SERVER_URL` with the generated domain\n5. Update the **Authorized redirect URI** in Google Cloud Console to `https://your-domain.railway.app/oauth/callback`\n\n#### Option B: Self-Host\n\n```bash\ngit clone https://github.com/navbuildz/gmail-mcp-server.git\ncd gmail-mcp-server\nnpm install\ncp .env.example .env\n# Edit .env with your values\nnpm run build\nnpm start\n```\n\n#### Option C: Docker\n\n```bash\ndocker build -t gmail-mcp-server .\ndocker run -p 3000:3000 \\\n  -e GOOGLE_CLIENT_ID=your-client-id \\\n  -e GOOGLE_CLIENT_SECRET=your-client-secret \\\n  -e ENCRYPTION_KEY=your-random-string \\\n  -e ADMIN_PASSWORD=your-password \\\n  -e SERVER_URL=https://your-domain.com \\\n  gmail-mcp-server\n```\n\n### Step 3: Connect Gmail Accounts\n\n1. Visit `https://your-server-url/setup`\n2. Enter your admin password\n3. Click **+ Add Gmail Account**\n4. Sign in with Google and grant permissions\n5. Repeat for each Gmail account you want to connect\n\n\u003e **Railway users:** After adding accounts, copy the `TOKENS_DATA` value shown on the setup page and add it as an environment variable in Railway. This keeps your accounts connected across redeploys.\n\n---\n\n## How to Connect Gmail MCP Server to Claude\n\n1. Go to [Claude](https://claude.ai) → Settings → Connectors\n2. Click **+** → Add custom connector\n3. Fill in:\n   - **Name**: `Gmail` (or any name you prefer)\n   - **Remote MCP server URL**: `https://your-server-url/mcp`\n   - Leave OAuth fields blank\n4. Click **Add**\n5. Start a new conversation and try: *\"List my connected Gmail accounts\"*\n\n---\n\n## How to Connect Gmail MCP Server to Cursor\n\nAdd to your Cursor MCP settings (`.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"gmail\": {\n      \"url\": \"https://your-server-url/mcp\"\n    }\n  }\n}\n```\n\n---\n\n## How to Connect Gmail MCP Server to Windsurf\n\nAdd to your Windsurf MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"gmail\": {\n      \"serverUrl\": \"https://your-server-url/mcp\"\n    }\n  }\n}\n```\n\n---\n\n## Multi-Account Gmail Setup\n\nConnect as many Gmail accounts as you need. Every tool accepts an `account` parameter:\n\n- Use a specific email: `\"account\": \"user@gmail.com\"`\n- Query all accounts at once: `\"account\": \"all\"`\n\n**Example prompts you can try:**\n- *\"Show me unread emails from the last 2 days across all accounts\"*\n- *\"Archive all promotional emails in user@gmail.com\"*\n- *\"Unsubscribe from newsletters in all accounts\"*\n- *\"Find emails with attachments from the last week in work@gmail.com\"*\n\n---\n\n## Auto-Unsubscribe from Newsletters with AI\n\nThe `unsubscribe_email` tool handles the entire unsubscribe process:\n\n1. Checks the `List-Unsubscribe` header (RFC 8058 one-click POST)\n2. Tries HTTP unsubscribe links from the header\n3. Sends an unsubscribe email via `mailto:` links\n4. Scans the email body for unsubscribe URLs\n5. Returns manual links if automatic unsubscribe isn't possible\n\nTry it: *\"Find newsletters from the last month and unsubscribe from all of them\"*\n\n---\n\n## Supported MCP Clients\n\n| Client | Status | Configuration |\n|---|---|---|\n| [Claude](https://claude.ai) (Web, Desktop, Code) | Supported | Custom connector → Remote MCP server URL |\n| [OpenClaw](https://openclaw.com) | Supported | MCP configuration |\n| [Cursor](https://cursor.com) | Supported | `.cursor/mcp.json` |\n| [Windsurf](https://codeium.com/windsurf) | Supported | MCP configuration |\n| [Cline](https://github.com/cline/cline) | Supported | MCP settings |\n| [Continue](https://continue.dev) | Supported | MCP configuration |\n| Any MCP-compatible client | Supported | Point to the `/mcp` endpoint |\n\n---\n\n## Architecture\n\n```\nAI Agent / Assistant (Claude, OpenClaw, Cursor, Windsurf, Cline)\n  ↓ MCP Protocol (Streamable HTTP)\nGmail MCP Server (Railway / Self-hosted / Docker)\n  ├── /mcp             MCP endpoint (tools)\n  ├── /setup           Admin page (add/remove accounts)\n  ├── /oauth/callback  Google OAuth callback\n  └── Token Store      Encrypted refresh tokens\n        ↓\nGmail API (per-account OAuth tokens)\n```\n\n---\n\n## Security\n\n- **OAuth 2.0** for authentication with Google\n- **AES-256-GCM** encrypted refresh token storage\n- **Minimal scopes** using only `gmail.readonly` and `gmail.modify`\n- **No passwords stored.** Your Gmail password never touches the server\n- **Password-protected setup.** The `/setup` page requires admin authentication\n- **Revocable anytime** from [Google Account Permissions](https://myaccount.google.com/permissions)\n\n---\n\n## Gmail Search Query Examples\n\nThe `list_emails` and `batch_process` tools accept Gmail's full search syntax:\n\n| Query | What it finds |\n|---|---|\n| `is:unread` | Unread emails |\n| `is:unread newer_than:2d` | Unread emails from the last 2 days |\n| `from:user@example.com` | Emails from a specific sender |\n| `subject:invoice` | Emails with \"invoice\" in the subject |\n| `has:attachment` | Emails with attachments |\n| `category:promotions` | Promotional emails |\n| `newer_than:7d` | Emails from the last week |\n| `after:2025/01/01 before:2025/02/01` | Emails in a date range |\n| `label:important is:unread` | Unread important emails |\n| `larger:5M` | Emails larger than 5MB |\n\n---\n\n## Contributing\n\nWant to help make this better? Here are some open ideas:\n\n- [ ] Add `send_email` tool for composing and sending emails\n- [ ] Add `reply_to_email` tool\n- [ ] Add email attachment download support\n- [ ] Add `delete_email` tool\n- [ ] Add `mark_as_read` / `mark_as_unread` tools\n- [ ] Add `remove_label` tool\n- [ ] Add support for Google Workspace accounts\n\nPRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## Tech Stack\n\n- **Runtime**: Node.js 20+\n- **Language**: TypeScript\n- **MCP SDK**: [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)\n- **Gmail API**: [googleapis](https://github.com/googleapis/google-api-nodejs-client)\n- **HTTP**: Express 5\n- **Auth**: Google OAuth 2.0\n\n---\n\n## License\n\n[MIT](LICENSE)\n\n---\n\nIf this project is useful to you, give it a star. It helps others find it.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavbuildz%2Fgmail-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnavbuildz%2Fgmail-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavbuildz%2Fgmail-mcp-server/lists"}