{
  "markdown": "# gmail-mcp\n\nMCP server for Gmail - read, send, archive, and manage emails.\n\n## Use Cases\n\n**Flight check-in**: \"Check me in for my flight tomorrow\" → finds your confirmation email, extracts the booking reference, and completes check-in with browser use.\n\n**Expense submission**: \"Submit my Amazon purchases from last week as expenses\" → finds receipts, extracts amounts/categories, and files them in your expense system.\n\n**Package tracking**: \"Where's my package from Acme?\" → finds the shipping notification, extracts the tracking number, and fetches current delivery status.\n\n**Find that attachment**: \"What did we settle on for the budget? Michelle sent me something yesterday\" → locates the email and opens the attached spreadsheet.\n\n**Vacation mode**: \"I'm on holiday Dec 20-Jan 2\" → sets up Gmail auto-reply, blocks your calendar, and updates your Slack status in one go.\n\n**Meeting follow-up**: After a call, your assistant reads the Gemini transcript, summarizes key decisions, and drafts a follow-up email with action items.\n\n(These are just examples - any workflow that needs email search, reading, or sending can use this.)\n\n## Setup\n\n### 1. Create Google OAuth credentials\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project (or use existing)\n3. Enable the Gmail API\n4. Go to **APIs & Services** → **OAuth consent screen**, set up consent screen\n5. Go to **APIs & Services** → **Credentials** → **Create Credentials** → **OAuth client ID**\n6. Choose **Web application**\n7. Add `http://localhost:3000/callback` to **Authorized redirect URIs**\n8. Note your Client ID and Client Secret\n\n### 2. Run the server\n\n```bash\nGOOGLE_CLIENT_ID='your-client-id' \\\nGOOGLE_CLIENT_SECRET='your-client-secret' \\\nMCP_TRANSPORT=http \\\nnpm start\n```\n\nThe server runs on `http://localhost:3000` by default. Change with `PORT=3001`.\n\n### 3. Add to your MCP client\n\nWith the server running, follow the instructions on [install-mcp](https://adamjones.me/install-mcp/?url=http://localhost:3000/mcp), which generates the right config for your MCP client (Claude Code, Claude Desktop, Cursor, Cline, VS Code, and more).\n\n## Architecture\n\nThis server acts as an **OAuth proxy** to Google:\n\n```mermaid\ngraph LR\n    A[MCP client] <--> B[gmail-mcp] <--> C[Google OAuth/API]\n```\n\n1. Server advertises itself as an OAuth authorization server via `/.well-known/oauth-authorization-server`\n2. `/register` returns the Google OAuth client credentials\n3. `/authorize` redirects to Google, encoding the client's callback URL in state\n4. `/callback` receives the code from Google and forwards to the client's callback\n5. `/token` proxies token requests to Google, injecting client credentials\n6. `/mcp` handles MCP requests, using the bearer token to call Gmail API\n\nThe server holds no tokens or state - it just proxies OAuth to Google.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `gmail_get_profile` | Get user's email address and profile info |\n| **Messages** | |\n| `gmail_messages_list` | Search/list messages (consider `gmail_threads_list` instead) |\n| `gmail_message_get` | Get a single message |\n| `gmail_message_send` | Send an email |\n| `gmail_message_forward` | Forward an email to new recipients |\n| `gmail_message_modify` | Add/remove labels |\n| `gmail_message_archive` | Archive (remove from inbox) |\n| `gmail_message_trash` | Move to trash |\n| `gmail_message_untrash` | Restore from trash |\n| `gmail_message_delete` | Permanently delete |\n| `gmail_messages_batch_modify` | Bulk label changes |\n| `gmail_messages_batch_delete` | Bulk permanent delete |\n| **Threads** | |\n| `gmail_threads_list` | Search/list threads (recommended) |\n| `gmail_thread_get` | Get all messages in a thread (recommended) |\n| `gmail_thread_modify` | Add/remove labels |\n| `gmail_thread_trash` | Move to trash |\n| `gmail_thread_untrash` | Restore from trash |\n| `gmail_thread_delete` | Permanently delete |\n| **Drafts** | |\n| `gmail_drafts_list` | List drafts |\n| `gmail_draft_get` | Get a draft |\n| `gmail_draft_create` | Create a draft |\n| `gmail_draft_update` | Update a draft |\n| `gmail_draft_send` | Send a draft |\n| `gmail_draft_delete` | Delete a draft |\n| **Labels** | |\n| `gmail_labels_list` | List all labels |\n| `gmail_label_get` | Get a label |\n| `gmail_label_create` | Create a label |\n| `gmail_label_update` | Update a label |\n| `gmail_label_delete` | Delete a label |\n| **Attachments** | |\n| `gmail_attachment_get` | Download attachment |\n| **Filters** | |\n| `gmail_filters_list` | List email filters |\n| `gmail_filter_get` | Get a filter |\n| `gmail_filter_create` | Create a filter |\n| `gmail_filter_delete` | Delete a filter |\n| **Settings** | |\n| `gmail_vacation_get` | Get vacation auto-reply settings |\n| `gmail_vacation_set` | Set vacation auto-reply settings |\n\n## Gmail API Scopes\n\n- `gmail.readonly` - Read messages and labels\n- `gmail.send` - Send messages\n- `gmail.modify` - Modify messages (archive, labels, trash)\n\n## Contributing\n\nPull requests are welcomed on GitHub! To get started:\n\n1. Install Git and Node.js\n2. Clone the repository\n3. Install dependencies with `npm install`\n4. Run `npm run test` to run tests\n5. Build with `npm run build`\n\n## Releases\n\nVersions follow the [semantic versioning spec](https://semver.org/).\n\nTo release:\n\n1. Use `npm version <major | minor | patch>` to bump the version\n2. Run `git push --follow-tags` to push with tags\n3. Wait for GitHub Actions to publish to the NPM registry.\n",
  "bytes": 5462,
  "sha": "fe5e44a7d907d744ab8488af36ba937f48683567fbb1d61947024d472d14df2d",
  "repo_slug": "domdomegg/gmail-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_domdomegg_gmail_mcp_d15f14e7/readme"
}