@renzo.johnson/gmail-mcp
v26.11.15
Published
Gmail MCP server for Claude Code, Cursor and any MCP client. Read, search, send and organize Gmail. mcprush.com-15fb5d66221658e29734f8bf
Maintainers
Readme
Gmail MCP
Gmail MCP server for Claude Code, Cursor and any MCP client. Read, search, send and organize Gmail.
npx -y @renzo.johnson/gmail-mcpThe server speaks MCP over stdio. It needs Node.js 22 or newer. Prefer VS Code? Install the Gmail MCP extension: it signs you in with a wizard and registers the server with 8 AI agents.
Sign in
The server uses the first credential it finds:
- An OAuth user: set
GOOGLE_OAUTH_CLIENT_ID,GOOGLE_OAUTH_CLIENT_SECRETandGOOGLE_OAUTH_REFRESH_TOKEN. Set all three or none; a partial set stops the server with an error naming what is missing. GOOGLE_APPLICATION_CREDENTIALS: path to a service-account key or anauthorized_userJSON file.- Application Default Credentials from the gcloud CLI:
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.sendThe OAuth refresh token (or service account) needs these scopes:
https://www.googleapis.com/auth/gmail.modifyhttps://www.googleapis.com/auth/gmail.readonlyhttps://www.googleapis.com/auth/gmail.send
Claude Code
Add it from the command line:
claude mcp add gmail-mcp -- npx -y @renzo.johnson/gmail-mcpOr add it to .mcp.json in your project (or ~/.claude.json for every project).
Cursor
Add it to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Configuration
Claude Code and Cursor use the same JSON shape:
With Application Default Credentials (gcloud):
{
"mcpServers": {
"gmail-mcp": {
"command": "npx",
"args": [
"-y",
"@renzo.johnson/gmail-mcp"
]
}
}
}With an OAuth user:
{
"mcpServers": {
"gmail-mcp": {
"command": "npx",
"args": [
"-y",
"@renzo.johnson/gmail-mcp"
],
"env": {
"GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
"GOOGLE_OAUTH_REFRESH_TOKEN": "your-refresh-token"
}
}
}
}With a service-account key:
{
"mcpServers": {
"gmail-mcp": {
"command": "npx",
"args": [
"-y",
"@renzo.johnson/gmail-mcp"
],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
}
}
}
}Available Tools (6)
Gmail (4 tools)
| Tool | What It Does | Example Prompt |
|------|-------------|----------------|
| gmail_list | List recent emails with metadata | "Show me my last 10 emails" |
| gmail_read | Read full email content by ID | "Read that email from John" |
| gmail_search | Search emails using Gmail query syntax | "Find emails from my boss this week" |
| gmail_send | Send an email | "Email the team about the meeting" |
Gmail Admin (mega-tool)
| Action | Description |
|--------|-------------|
| create_draft | Create a new email draft |
| update_draft | Update an existing draft |
| delete_draft | Delete a draft (requires confirm) |
| add_label / remove_label | Manage message labels |
| create_label / delete_label | Create or delete labels |
| trash / untrash | Move to/from trash (trash requires confirm) |
| mark_read / mark_unread | Toggle read status |
Safety
Destructive actions (delete, trash, clear) require confirm: true to execute. The AI agent will be warned and must explicitly confirm before proceeding.
Privacy
The server sends no telemetry. It talks only to Google APIs, with your own credentials.
Links
By Renzo Johnson | MIT License
