gmail — Claude Code MCP server: Gmail inside your agent
Hooks Gmail into an AI assistant: read threads, search, label, draft and send. Works for personal accounts and Google Workspace.
claude mcp add --env GMAIL_OAUTH_CLIENT_ID=<GMAIL_OAUTH_CLIENT_ID> --env GMAIL_OAUTH_CLIENT_SECRET=<GMAIL_OAUTH_CLIENT_SECRET> --env GMAIL_OAUTH_REFRESH_TOKEN=<GMAIL_OAUTH_REFRESH_TOKEN> --env GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL> --env GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY=<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY> --transport stdio gmail -- npx -y gmail-workspace-mcp-serverWhat gmail does
The server hands your agent a set of Gmail tools. It can pull conversation lists filtered by label, fetch a full message with attachment details, and run searches in Gmail query syntax. Labels, read/unread state, stars and archiving are all writable, and drafts or replies can be created and sent.
Auth comes in two flavours. A personal @gmail.com mailbox uses OAuth2: enable the Gmail API in a Google Cloud project, set up and publish the consent screen, then make Desktop app credentials. Grab the refresh token with npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>; the server listens on port 3000 unless you override it with PORT. Workspace setups go through a service account with domain-wide delegation and the four Gmail scopes.
Permissions are split into tool groups picked with GMAIL_ENABLED_TOOLGROUPS: readonly, readwrite, and readwrite_external, which adds sending. All of them are on out of the box, so the agent can send mail on the first run. Skip publishing the consent screen and the refresh token lapses every 7 days.
What it helps with
- locate a message using Gmail search syntax
- read a thread and list its attachments
- prepare a reply draft from task context
- file incoming mail under the right labels
- lock an agent down to read-only mailbox access
Example prompts for the agent
- Search Gmail for the thread with the contractor from March and show the latest message
- Draft a reply to that message and save it in Gmail
- Send an email to the address in
contacts.mdwith the subject “Friday call”
How to install gmail
Platform CLI
claude mcp add --env GMAIL_OAUTH_CLIENT_ID=<GMAIL_OAUTH_CLIENT_ID> --env GMAIL_OAUTH_CLIENT_SECRET=<GMAIL_OAUTH_CLIENT_SECRET> --env GMAIL_OAUTH_REFRESH_TOKEN=<GMAIL_OAUTH_REFRESH_TOKEN> --env GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL> --env GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY=<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY> --transport stdio gmail -- npx -y gmail-workspace-mcp-serverReplace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
codex mcp add gmail --env GMAIL_OAUTH_CLIENT_ID=<GMAIL_OAUTH_CLIENT_ID> --env GMAIL_OAUTH_CLIENT_SECRET=<GMAIL_OAUTH_CLIENT_SECRET> --env GMAIL_OAUTH_REFRESH_TOKEN=<GMAIL_OAUTH_REFRESH_TOKEN> --env GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL> --env GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY=<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY> -- npx -y gmail-workspace-mcp-serverReplace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"-y",
"gmail-workspace-mcp-server"
],
"env": {
"GMAIL_OAUTH_CLIENT_ID": "<GMAIL_OAUTH_CLIENT_ID>",
"GMAIL_OAUTH_CLIENT_SECRET": "<GMAIL_OAUTH_CLIENT_SECRET>",
"GMAIL_OAUTH_REFRESH_TOKEN": "<GMAIL_OAUTH_REFRESH_TOKEN>",
"GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL>",
"GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Config file
{
"servers": {
"gmail": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"gmail-workspace-mcp-server"
],
"env": {
"GMAIL_OAUTH_CLIENT_ID": "<GMAIL_OAUTH_CLIENT_ID>",
"GMAIL_OAUTH_CLIENT_SECRET": "<GMAIL_OAUTH_CLIENT_SECRET>",
"GMAIL_OAUTH_REFRESH_TOKEN": "<GMAIL_OAUTH_REFRESH_TOKEN>",
"GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL>",
"GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY>"
}
}
}
}Replace <…> with your own values. 2 more environment variables are in the server README
Platform CLI
gemini mcp add -e GMAIL_OAUTH_CLIENT_ID=<GMAIL_OAUTH_CLIENT_ID> -e GMAIL_OAUTH_CLIENT_SECRET=<GMAIL_OAUTH_CLIENT_SECRET> -e GMAIL_OAUTH_REFRESH_TOKEN=<GMAIL_OAUTH_REFRESH_TOKEN> -e GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL=<GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL> -e GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY=<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY> gmail npx -y gmail-workspace-mcp-serverReplace <…> with your own values. 2 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about gmail
How do I install gmail in Claude Code?
Run `claude mcp add gmail -e GMAIL_OAUTH_CLIENT_ID=<GMAIL_OAUTH_CLIENT_ID> -e GMAIL_OAUTH_CLIENT_SECRET=<GMAIL_OAUTH_CLIENT_SECRET> -e GMAIL_OAUTH_REFRESH_TOKEN=<GMAIL_OAUTH_REFRESH_TOKEN> -e GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY=<GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY> -- npx -y gmail-workspace-mcp-server` with your own credential values filled in.
What does the gmail MCP server do?
It lets your assistant work with a mailbox: read conversations, search, change labels and message state, write drafts, send mail. Every call goes through the Gmail API under your credentials.
Should I use OAuth2 or a service account?
Pick OAuth2 for a personal mailbox where you grant access yourself. A service account with domain-wide delegation is the route inside Google Workspace, where a domain admin hands out the scopes.
