{"id":50189575,"url":"https://github.com/ihiteshgupta/gmail-mcp-server","last_synced_at":"2026-05-25T12:03:53.191Z","repository":{"id":347275782,"uuid":"1129544064","full_name":"ihiteshgupta/gmail-mcp-server","owner":"ihiteshgupta","description":"Gmail MCP Server for Claude Code - Search, send, and manage emails via AI","archived":false,"fork":false,"pushed_at":"2026-03-27T07:22:36.000Z","size":32,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T19:27:36.114Z","etag":null,"topics":["ai-tools","claude-code","email","gmail","javascript","mcp"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/ihiteshgupta.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-01-07T08:37:24.000Z","updated_at":"2026-03-27T07:22:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ihiteshgupta/gmail-mcp-server","commit_stats":null,"previous_names":["ihiteshgupta/gmail-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ihiteshgupta/gmail-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihiteshgupta%2Fgmail-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihiteshgupta%2Fgmail-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihiteshgupta%2Fgmail-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihiteshgupta%2Fgmail-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ihiteshgupta","download_url":"https://codeload.github.com/ihiteshgupta/gmail-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihiteshgupta%2Fgmail-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33473709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: 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-tools","claude-code","email","gmail","javascript","mcp"],"created_at":"2026-05-25T12:03:48.935Z","updated_at":"2026-05-25T12:03:53.182Z","avatar_url":"https://github.com/ihiteshgupta.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gmail-mcp-server\n\n\u003e Gmail MCP Server — read, send, search, and manage Gmail through Claude using Google's official API.\n\n[![npm version](https://img.shields.io/npm/v/@dev-hitesh-gupta/gmail-mcp-server.svg)](https://www.npmjs.com/package/@dev-hitesh-gupta/gmail-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)\n\n**19 tools** for emails, drafts, labels, threads, and attachments — powered by the official Google Gmail API with OAuth 2.0. Works with any Google account (personal Gmail or Google Workspace).\n\n## Tools\n\n### Email Operations (5)\n\n| Tool | Description |\n|------|-------------|\n| `gmail_search` | Search emails using Gmail query syntax |\n| `gmail_get_message` | Get full email content by ID |\n| `gmail_send` | Send an email (supports CC, BCC, reply threading) |\n| `gmail_get_thread` | Get all messages in a thread |\n| `gmail_get_profile` | Get your Gmail profile info |\n\n### Drafts (4)\n\n| Tool | Description |\n|------|-------------|\n| `gmail_create_draft` | Create a draft email |\n| `gmail_list_drafts` | List all saved drafts |\n| `gmail_send_draft` | Send an existing draft |\n| `gmail_delete_draft` | Delete a draft |\n\n### Labels (3)\n\n| Tool | Description |\n|------|-------------|\n| `gmail_list_labels` | List all labels |\n| `gmail_create_label` | Create a new label |\n| `gmail_delete_label` | Delete a label |\n\n### Message Management (4)\n\n| Tool | Description |\n|------|-------------|\n| `gmail_trash` | Move email to trash |\n| `gmail_untrash` | Restore email from trash |\n| `gmail_mark_read` | Mark email as read |\n| `gmail_mark_unread` | Mark email as unread |\n| `gmail_modify_labels` | Add or remove labels from an email |\n\n### Attachments (2)\n\n| Tool | Description |\n|------|-------------|\n| `gmail_list_attachments` | List all attachments in an email |\n| `gmail_get_attachment` | Download attachment as base64 |\n\n---\n\n## Setup\n\nThis server uses Google's official Gmail API. You need to create OAuth 2.0 credentials once in Google Cloud Console — this takes about 5 minutes.\n\n### Step 1 — Create a Google Cloud Project\n\n1. Go to [console.cloud.google.com](https://console.cloud.google.com/)\n2. Click the project dropdown at the top → **\"New Project\"**\n3. Give it a name (e.g. `gmail-mcp`) and click **Create**\n4. Make sure the new project is selected\n\n### Step 2 — Enable the Gmail API\n\n1. In the left menu go to **\"APIs \u0026 Services\"** → **\"Library\"**\n2. Search for **\"Gmail API\"**\n3. Click it → click **\"Enable\"**\n\n### Step 3 — Configure OAuth Consent Screen\n\n1. Go to **\"APIs \u0026 Services\"** → **\"OAuth consent screen\"**\n2. Choose **\"External\"** (works for any Google account) → click **Create**\n3. Fill in:\n   - **App name**: `Gmail MCP Server` (or anything)\n   - **User support email**: your email\n   - **Developer contact email**: your email\n4. Click **Save and Continue**\n5. On the **Scopes** page, click **\"Add or Remove Scopes\"** and add these:\n   ```\n   https://www.googleapis.com/auth/gmail.readonly\n   https://www.googleapis.com/auth/gmail.send\n   https://www.googleapis.com/auth/gmail.compose\n   https://www.googleapis.com/auth/gmail.modify\n   https://www.googleapis.com/auth/gmail.labels\n   ```\n6. Click **Save and Continue**\n7. On **Test users**, click **\"Add Users\"** → add your Gmail address\n8. Click **Save and Continue** → **Back to Dashboard**\n\n### Step 4 — Create OAuth Client ID\n\n1. Go to **\"APIs \u0026 Services\"** → **\"Credentials\"**\n2. Click **\"+ Create Credentials\"** → **\"OAuth client ID\"**\n3. Application type: **\"Desktop app\"**\n4. Name: `Gmail MCP Server`\n5. Click **Create**\n6. Click **\"Download JSON\"** — save this file, you'll need it next\n\n### Step 5 — Install \u0026 Authenticate\n\n```bash\n# Install the package\nnpm install -g @dev-hitesh-gupta/gmail-mcp-server\n\n# Install dependencies for first run\nnpx playwright install chromium 2\u003e/dev/null; true\n\n# Create config directory and place your credentials\nmkdir -p ~/.gmail-mcp\ncp /path/to/downloaded-credentials.json ~/.gmail-mcp/credentials.json\n\n# Authenticate — opens a browser window for Google sign-in\ngmail-mcp-server auth\n```\n\nYour token is saved to `~/.gmail-mcp/token.json` and auto-refreshed on expiry.\n\n### Step 6 — Add to Claude Code\n\n```bash\nclaude mcp add gmail -- npx @dev-hitesh-gupta/gmail-mcp-server\n```\n\nOr manually in your Claude config (`~/.claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"gmail\": {\n      \"command\": \"npx\",\n      \"args\": [\"@dev-hitesh-gupta/gmail-mcp-server\"]\n    }\n  }\n}\n```\n\n---\n\n## Multiple Accounts\n\nYou can connect multiple Gmail accounts by running separate server instances with different config directories:\n\n```json\n{\n  \"mcpServers\": {\n    \"gmail-work\": {\n      \"command\": \"npx\",\n      \"args\": [\"@dev-hitesh-gupta/gmail-mcp-server\"],\n      \"env\": { \"GMAIL_MCP_CONFIG_DIR\": \"~/.gmail-mcp-work\" }\n    },\n    \"gmail-personal\": {\n      \"command\": \"npx\",\n      \"args\": [\"@dev-hitesh-gupta/gmail-mcp-server\"],\n      \"env\": { \"GMAIL_MCP_CONFIG_DIR\": \"~/.gmail-mcp-personal\" }\n    }\n  }\n}\n```\n\nAuthenticate each separately:\n```bash\nGMAIL_MCP_CONFIG_DIR=~/.gmail-mcp-work gmail-mcp-server auth\nGMAIL_MCP_CONFIG_DIR=~/.gmail-mcp-personal gmail-mcp-server auth\n```\n\n---\n\n## Gmail Search Syntax\n\nThe `gmail_search` tool supports the full Gmail query language:\n\n```\nfrom:boss@company.com           # From specific sender\nto:me                           # Sent to you\nsubject:invoice                 # Subject contains word\nis:unread                       # Unread emails\nis:starred                      # Starred emails\nhas:attachment                  # Has attachments\nafter:2024/01/01                # After date\nbefore:2024/12/31               # Before date\nlabel:work                      # Has label\nin:inbox                        # In inbox\nin:sent                         # In sent\nin:spam                         # In spam\n```\n\nCombine queries:\n```\nfrom:client@company.com is:unread has:attachment\nsubject:urgent OR subject:important\nfrom:boss@company.com after:2024/06/01\n```\n\n---\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `GMAIL_MCP_CONFIG_DIR` | `~/.gmail-mcp` | Directory for credentials and token |\n\n---\n\n## Data \u0026 Auth Storage\n\nAll data is stored locally:\n\n```\n~/.gmail-mcp/\n├── credentials.json    # Your Google OAuth client credentials\n└── token.json          # Access + refresh token (auto-managed)\n```\n\n\u003e **Security:** Never commit `credentials.json` or `token.json` to version control. Add `~/.gmail-mcp/` to your `.gitignore`.\n\n---\n\n## Troubleshooting\n\n**\"Not authenticated\" / \"Credentials not found\":**\n```bash\n# Make sure credentials.json is in place\nls ~/.gmail-mcp/credentials.json\n\n# Re-authenticate\ngmail-mcp-server auth\n```\n\n**Token expired:**\n```bash\nrm ~/.gmail-mcp/token.json\ngmail-mcp-server auth\n```\n\n**\"Access blocked\" during Google sign-in:**\nYour OAuth app is in test mode. Go to Google Cloud Console → OAuth consent screen → add your email under **Test users**.\n\n**Scope errors:**\nEnsure all 5 Gmail scopes are added in the OAuth consent screen (Step 3 above).\n\n---\n\n## Requirements\n\n- Node.js 18+\n- A Google account (personal Gmail or Google Workspace)\n- Google Cloud project with Gmail API enabled (see setup above)\n\n## License\n\nMIT — [Hitesh Gupta](https://github.com/dev-hitesh-gupta)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fihiteshgupta%2Fgmail-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fihiteshgupta%2Fgmail-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fihiteshgupta%2Fgmail-mcp-server/lists"}