multi-gmail-mcp — Claude Code MCP server: features and setup
This MCP server connects multiple Gmail accounts to an AI client for search, replies, drafts, and mailbox labels. It fits chat-based email work.
claude mcp add --env GOOGLE_CLIENT_ID=<GOOGLE_CLIENT_ID> --env GOOGLE_CLIENT_SECRET=<GOOGLE_CLIENT_SECRET> --transport stdio multi-gmail-mcp -- npx -y multi-gmail-mcpWhat multi-gmail-mcp does
multi-gmail-mcp gives an agent access to several Gmail accounts at once. Its tools search mail with Gmail query syntax, fetch complete messages, send email, reply inside a thread, and save drafts. Mailbox actions include adding or removing labels, archiving messages, and changing read status.
The package exposes the gmail-mcp server and the gmail-mcp-cli account manager. OAuth tokens are kept in ~/.gmail-mcp-tokens.db and refreshed automatically. The server uses stdio only, so it does not open a network port. Check Node.js >= 22.5.0 first; the server will not run without it.
Setup also needs a Google Cloud project with the Gmail API enabled, a desktop OAuth credential, and the scopes gmail.readonly, gmail.send, gmail.modify, and gmail.labels. Credentials can live in ~/.gmail-mcp-oauth.json or be supplied through GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.
What it helps with
- search Gmail with native query syntax
- read complete email messages
- send mail from selected accounts
- reply within an existing thread
- archive messages and manage labels
Example prompts for the agent
- List all authenticated Gmail accounts.
- Search
[email protected]for unread messages received this week. - Reply from my personal account and say that I will be there on Saturday.
How to install multi-gmail-mcp
Platform CLI
claude mcp add --env GOOGLE_CLIENT_ID=<GOOGLE_CLIENT_ID> --env GOOGLE_CLIENT_SECRET=<GOOGLE_CLIENT_SECRET> --transport stdio multi-gmail-mcp -- npx -y multi-gmail-mcpReplace <…> with your own values
Platform CLI
codex mcp add multi-gmail-mcp --env GOOGLE_CLIENT_ID=<GOOGLE_CLIENT_ID> --env GOOGLE_CLIENT_SECRET=<GOOGLE_CLIENT_SECRET> -- npx -y multi-gmail-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"multi-gmail-mcp": {
"command": "npx",
"args": [
"-y",
"multi-gmail-mcp"
],
"env": {
"GOOGLE_CLIENT_ID": "<GOOGLE_CLIENT_ID>",
"GOOGLE_CLIENT_SECRET": "<GOOGLE_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"multi-gmail-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"multi-gmail-mcp"
],
"env": {
"GOOGLE_CLIENT_ID": "<GOOGLE_CLIENT_ID>",
"GOOGLE_CLIENT_SECRET": "<GOOGLE_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e GOOGLE_CLIENT_ID=<GOOGLE_CLIENT_ID> -e GOOGLE_CLIENT_SECRET=<GOOGLE_CLIENT_SECRET> multi-gmail-mcp npx -y multi-gmail-mcpReplace <…> with your own values
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 multi-gmail-mcp
How do I install multi-gmail-mcp in Claude Code?
Run claude mcp add multi-gmail-mcp -e GOOGLE_CLIENT_SECRET=<GOOGLE_CLIENT_SECRET> -- npx -y multi-gmail-mcp.
What does multi-gmail-mcp do?
It exposes several Gmail accounts to an agent for mail search, reading, sending, threaded replies, drafts, and label operations.
What is required for Gmail authentication?
Use a Google Cloud project with the Gmail API enabled, OAuth credentials, and the required Gmail scopes. Node.js >= 22.5.0 is also required.
