{"_id":"@arvoretech/gmail-mcp","_rev":"4-10eec555779173a218f4c9900f2ce5b9","name":"@arvoretech/gmail-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@arvoretech/gmail-mcp","version":"1.0.0","keywords":["mcp","gmail","google-workspace","email","oauth","llm","ai","arvore"],"author":{"name":"Arvore"},"license":"MIT","_id":"@arvoretech/gmail-mcp@1.0.0","maintainers":[{"name":"joao.barros.arvore","email":"joao.barros@arvore.com.br"},{"name":"ricardoraposorfox","email":"ricardorbxx1@gmail.com"},{"name":"vitor.piovezan","email":"vitor.piovezan@arvore.com.br"}],"homepage":"https://github.com/arvoreeducacao/arvore-mcp-servers#readme","bugs":{"url":"https://github.com/arvoreeducacao/arvore-mcp-servers/issues"},"bin":{"gmail-mcp":"dist/index.js"},"dist":{"shasum":"70ae85765583a24356217201711502c70b87da1a","tarball":"https://registry.npmjs.org/@arvoretech/gmail-mcp/-/gmail-mcp-1.0.0.tgz","fileCount":19,"integrity":"sha512-PhWML39jmynwfPOpifknx4RqZtkbCn2t+6EDDVVR9Erfsna8aT1Q/WufoBeCLRMeSnakeX3lmO0BBs0lVqehaA==","signatures":[{"sig":"MEQCICGUYudI+yrnpykbQZ+OWiSuZS1TA1HY0hbcITiYT/8jAiBNhoaP9wHa5xTc9g0u9KhqcbE3KxzMHbxf/QGgmAffzA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":100757},"main":"dist/index.js","type":"module","_from":"file:arvoretech-gmail-mcp-1.0.0.tgz","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","test":"vitest run --passWithNoTests","build":"tsc","start":"node dist/index.js","lint:fix":"eslint src/**/*.ts --fix","test:cov":"vitest run --coverage --passWithNoTests"},"_npmUser":{"name":"ricardoraposorfox","email":"ricardorbxx1@gmail.com"},"_resolved":"/tmp/e93f03441ff77e3079a24d03f62a9ba4/arvoretech-gmail-mcp-1.0.0.tgz","_integrity":"sha512-PhWML39jmynwfPOpifknx4RqZtkbCn2t+6EDDVVR9Erfsna8aT1Q/WufoBeCLRMeSnakeX3lmO0BBs0lVqehaA==","repository":{"url":"git+https://github.com/arvoreeducacao/arvore-mcp-servers.git","type":"git","directory":"packages/gmail"},"_npmVersion":"11.13.0","description":"Gmail MCP Server — read, send, and manage Gmail messages via OAuth user flow","directories":{},"_nodeVersion":"26.1.0","dependencies":{"zod":"^3.22.4","@modelcontextprotocol/sdk":"~1.22.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/gmail-mcp_1.0.0_1779996271356_0.8710314886622246","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-28T19:24:30.870Z","modified":"2026-06-16T21:13:11.425Z","1.0.0":"2026-05-28T19:24:31.518Z"},"bugs":{"url":"https://github.com/arvoreeducacao/arvore-mcp-servers/issues"},"author":{"name":"Arvore"},"license":"MIT","homepage":"https://github.com/arvoreeducacao/arvore-mcp-servers#readme","keywords":["mcp","gmail","google-workspace","email","oauth","llm","ai","arvore"],"repository":{"url":"git+https://github.com/arvoreeducacao/arvore-mcp-servers.git","type":"git","directory":"packages/gmail"},"description":"Gmail MCP Server — read, send, and manage Gmail messages via OAuth user flow","maintainers":[{"email":"joao.barros@arvore.com.br","name":"joao.barros.arvore"},{"email":"rafasouza@protonmail.com","name":"rafsouza"},{"email":"pedro.adas@gmail.com","name":"pedro.adas"},{"email":"guilhermebscontact@gmail.com","name":"guilhermebs"},{"email":"ricardorbxx1@gmail.com","name":"ricardoraposorfox"},{"email":"jvgcunha2002@gmail.com","name":"jott4"},{"email":"vitor.piovezan@arvore.com.br","name":"vitor.piovezan"}],"readme":"# @arvoretech/gmail-mcp\n\nMCP server for Gmail — read, send, and manage messages from your AI assistant. OAuth user flow (no service account required).\n\n## Tools\n\n| Tool              | Description                                                          |\n| ----------------- | -------------------------------------------------------------------- |\n| `messages_list`   | List messages with Gmail search syntax (`from:`, `is:unread`, etc.)  |\n| `messages_get`    | Get a message with parsed headers and body                           |\n| `threads_get`     | Get an entire email thread end-to-end                                |\n| `drafts_list`     | List existing drafts                                                 |\n| `drafts_create`   | Create a draft (always available, even when sending is disabled)     |\n| `drafts_send`     | Send an existing draft (requires `GMAIL_MCP_ALLOW_SEND=true`)        |\n| `messages_send`   | Send an email immediately (requires `GMAIL_MCP_ALLOW_SEND=true`)     |\n| `messages_modify` | Add/remove labels (mark read, archive, star, etc.)                   |\n| `messages_trash`  | Move a message to trash                                              |\n| `labels_list`     | List system + user labels                                            |\n| `profile_get`     | Get the authenticated user's profile                                 |\n\nReply threading: `messages_send` and `drafts_create` accept `replyToMessageId` and automatically populate `In-Reply-To`, `References`, and `threadId` so replies show up correctly in Gmail.\n\n## Setup\n\n### 1. Create OAuth Client in Google Cloud Console\n\n1. Open the [Cloud Console](https://console.cloud.google.com/apis/credentials)\n2. Select or create a project\n3. Enable the [Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)\n4. Open **OAuth consent screen**:\n   - User type: **External**\n   - Add yourself under **Test users** (required while the app is in testing mode)\n5. Open **Credentials** → **Create Credentials** → **OAuth client ID**:\n   - Application type: **Desktop app**\n   - Save the `client_id` and `client_secret`\n\n### 2. Authorize\n\n```bash\nexport GMAIL_MCP_CLIENT_ID=\"your-client-id\"\nexport GMAIL_MCP_CLIENT_SECRET=\"your-client-secret\"\n\nnpx @arvoretech/gmail-mcp auth login\n```\n\nThis opens your browser, you sign in and approve scopes, and the MCP captures the refresh token. Credentials are encrypted at rest (AES-256-GCM) with the key stored in:\n\n- macOS: the system keychain (`security` utility)\n- Other platforms: a file at `~/.config/arvoretech-gmail-mcp/.encryption_key` (mode 0600)\n\n### 3. Use as MCP server\n\nAdd to your MCP client config (Kiro, Claude Desktop, Cursor, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"gmail\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@arvoretech/gmail-mcp\"],\n      \"env\": {\n        \"GMAIL_MCP_CLIENT_ID\": \"your-client-id\",\n        \"GMAIL_MCP_CLIENT_SECRET\": \"your-client-secret\",\n        \"GMAIL_MCP_ALLOW_SEND\": \"false\"\n      }\n    }\n  }\n}\n```\n\nBy default the MCP runs in **read + draft mode** — `messages_send` and `drafts_send` are not registered. Set `GMAIL_MCP_ALLOW_SEND=true` only when you trust the agent to send mail without human review.\n\n## Subcommands\n\n| Command                   | Description                              |\n| ------------------------- | ---------------------------------------- |\n| `gmail-mcp auth login`    | Browser-based OAuth flow                 |\n| `gmail-mcp auth logout`   | Revoke refresh token and clear credentials |\n| `gmail-mcp auth status`   | Print current auth status                |\n| `gmail-mcp` (no args)     | Run as MCP stdio server                  |\n\n## Environment Variables\n\n| Variable                       | Required | Description                                                            |\n| ------------------------------ | -------- | ---------------------------------------------------------------------- |\n| `GMAIL_MCP_CLIENT_ID`          | Yes      | OAuth client ID from Google Cloud Console                              |\n| `GMAIL_MCP_CLIENT_SECRET`      | Yes      | OAuth client secret                                                    |\n| `GMAIL_MCP_ALLOW_SEND`         | No       | Set to `true` to enable `messages_send` and `drafts_send` tools        |\n| `GMAIL_MCP_REFRESH_TOKEN`      | No       | Bypass the token store and use a refresh token directly (CI / Docker) |\n| `GMAIL_MCP_CONFIG_DIR`         | No       | Override config directory (default: `~/.config/arvoretech-gmail-mcp`)  |\n| `GMAIL_MCP_REDIRECT_PORT`      | No       | Force a specific port for the OAuth callback (default: random)         |\n| `GMAIL_MCP_LOGIN_HINT`         | No       | Pre-fill the email address in the consent screen                       |\n\n## OAuth Scopes\n\nThe MCP requests these scopes (well within Google's 25-scope limit for unverified apps):\n\n- `https://www.googleapis.com/auth/gmail.readonly` — read messages and labels\n- `https://www.googleapis.com/auth/gmail.send` — send mail\n- `https://www.googleapis.com/auth/gmail.modify` — modify labels (mark read, archive, star, trash)\n- `https://www.googleapis.com/auth/gmail.compose` — create drafts\n\nTo grant fewer permissions, edit `DEFAULT_SCOPES` in `src/oauth.ts` before `auth login` and re-authorize.\n\n## Headless / CI usage\n\nFor environments without a browser or keychain (Docker, EKS, GitHub Actions):\n\n1. Run `gmail-mcp auth login` once on a machine with a browser.\n2. Read the refresh token from the saved credentials and pass it through:\n\n```bash\nexport GMAIL_MCP_CLIENT_ID=\"...\"\nexport GMAIL_MCP_CLIENT_SECRET=\"...\"\nexport GMAIL_MCP_REFRESH_TOKEN=\"ya29...\"\ngmail-mcp\n```\n\nWhen `GMAIL_MCP_REFRESH_TOKEN` is set, the disk store is bypassed entirely.\n\n## Development\n\n```bash\npnpm install\npnpm build\npnpm test\npnpm lint\n```\n\n## Security notes\n\n- Refresh tokens are long-lived. Treat them like passwords.\n- The encryption key never leaves your machine — it lives in the macOS keychain or a `0600` file.\n- `messages_send` is gated behind `GMAIL_MCP_ALLOW_SEND` so an agent can't send mail unless you opt in.\n- Always prefer `drafts_create` for AI-generated emails — humans review before sending.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}