Gmail MCP

Gmail MCP

Local Gmail tools for GitHub Copilot CLI, backed by Google's official Gmail API.

This project is a standalone local MCP server, not a Copilot plugin. Copilotstarts it as a user-configured stdio process.

[!IMPORTANT]OAuth credentials and direct Gmail API traffic remain on this PC, but emailcontent returned by MCP tools may be sent to GitHub Copilot's hosted modelservices. Do not use this integration if mailbox content must never leave thecomputer.

Documentation

• Windows quickstart
• Google OAuth setup
• Sharing with another user
• Personal data boundaries
• Architecture
• Tool reference
• Security model
• Setup and operations
• Troubleshooting
• Design decisions and alternatives
• Change history
• Agent and contributor guidance
• Safe Gmail skill

Safety model

• Requests gmail.modify for mailbox actions and gmail.settings.basic forfilter management, never the permanent-delete https://mail.google.com/scope.
• Sending is draft-first. gmail_send_draft returns a state-bound confirmationtoken before it can send.
• Deletion accepts message IDs only and moves them to recoverable Gmail Trash.
• OAuth refresh tokens are stored in Windows Credential Manager. Access tokensremain in memory.
• Write tools are marked as mutating/destructive for Copilot confirmations.Keep confirmations enabled and do not use /allow-all with this server.
• Persistent filters cannot forward mail or automate Trash/Spam actions.
• Attachment content download is not supported; only metadata is exposed.

Google Cloud setup

See Setup and operations for the complete Google Cloudworkflow, including multiple-account selection, test users, scope setup, missingJSON downloads, client-secret compatibility, publishing, and cleanup.

Quick start

git clone https://github.com/Evyatar108/gmail-mcp.git
Set-Location gmail-mcp
.\scripts\setup-copilot.ps1
.\scripts\install-oauth-client.ps1 -Path C:\Downloads\client_secret.json
.\.venv\Scripts\gmail-mcp.exe auth
.\.venv\Scripts\gmail-mcp.exe status

Authorization opens the system browser, requests offline access, verifies theauthenticated account and granted scopes, and stores the refresh token inWindows Credential Manager.

setup-copilot.ps1 registers the exact 15-tool allowlist using the clonedrepository's absolute executable path and installs the three public safety/setupskills.

The server is non-interactive. If authorization is absent or revoked, Gmailtools return an error directing you to run gmail-mcp auth; the stdio servernever launches a browser.

Typical flow

1. Search: Use gmail_search to find receipts from last month.
2. Read: Use gmail_get_message for message ID ...
3. Draft: Create a draft reply, but do not send it.
4. Send: call gmail_send_draft without confirmation to receive the exactpreview token, review it, then call again with that token.
5. Trash: call gmail_trash without confirmation to receive the exact previewtoken, review the listed message IDs, then call again with that token.
6. Rules: create a label, preview a safe filter, then approve the nativedestructive-tool prompt before filter creation or deletion.

Gmail Trash retention is time-limited. gmail_untrash works only while Gmailstill retains the message.

For complete schemas, limits, and confirmation behavior, seeTool reference.

Credential status and revocation

.\.venv\Scripts\gmail-mcp.exe status
.\.venv\Scripts\gmail-mcp.exe revoke

Revocation removes the Google grant and then deletes the WinVault entry.Already in-flight Google requests cannot be cancelled, and an issued accesstoken may remain accepted briefly after revocation. Each new tool call rechecksWinVault and fails closed once the record is removed or changed.

Development

uv run pytest
uv build

Install or refresh all three public Gmail skills:

.\scripts\install-user-skill.ps1