Overview
The Gmail integration uses @gongrzhe/server-gmail-autoauth-mcp as an MCP server, providing Gmail tools to your agent. It can operate in two modes:Tool-only mode
The agent gets Gmail tools but doesn’t monitor the inbox:mcp__gmail__send_email- Send emailsmcp__gmail__read_email- Read specific emails by IDmcp__gmail__search_emails- Search with Gmail query syntaxmcp__gmail__create_draft- Create draft emailsmcp__gmail__list_labels- List Gmail labels
Channel mode
Everything from tool-only mode, plus:- Polls inbox for new emails (every 60 seconds)
- Triggers agent on matching emails
- Notifies via your main channel (e.g., WhatsApp)
- Filters: Primary inbox only by default (excludes Promotions, Social, etc.)
Adding Gmail
Use the/add-gmail skill:
Choose mode
- Tool-only - Agent can use Gmail tools when triggered from other channels
- Channel mode - Agent monitors inbox and triggers on new emails
Apply code changes
The skill applies different changes depending on mode:Tool-only:
- Mounts
~/.gmail-mcpin container - Adds Gmail MCP server to agent runner
- All of the above, plus:
- Adds
src/channels/gmail.ts(GmailChannel implementation) - Adds
src/channels/gmail.test.ts(unit tests) - Merges Gmail channel into
src/index.ts - Installs
googleapisNPM package
GCP OAuth setup
Gmail integration requires Google Cloud OAuth credentials.Create GCP project
- Open console.cloud.google.com
- Create a new project or select existing
Create OAuth credentials
- Go to APIs & Services → Credentials
- Click + CREATE CREDENTIALS → OAuth client ID
- If prompted for consent screen:
- Choose External
- Fill in app name and email
- Save
- Application type: Desktop app
- Name: anything (e.g., “NanoClaw Gmail”)
Authorization
After placing the OAuth credentials file, authorize Gmail access:- Sign in to your Google account
- If you see “app isn’t verified” warning:
- Click Advanced
- Click Go to [app name] (unsafe)
- This is normal for personal OAuth apps
- Grant the requested permissions
~/.gmail-mcp/credentials.json.
The MCP server automatically refreshes OAuth tokens. You only need to authorize once unless you revoke access.
Build and restart
After authorization:Testing Gmail tools
Send a message in your main channel:Check MCP server
Test the MCP server directly:Channel mode setup
If you chose channel mode, the agent monitors your inbox for new emails.Default filter
By default, only emails in the Primary inbox trigger the agent:- Promotions
- Social
- Updates
- Forums
Custom filters
Editsrc/channels/gmail.ts to customize the filter:
Email notifications
When an email triggers the agent, it notifies via your main channel:CLAUDE.md instructions
The skill adds these instructions togroups/main/CLAUDE.md:
JID format
In channel mode, emails use thegmail: prefix:
- Email:
gmail:<message-id>
gmail:18d4a2f8e6c9b1a3
Implementation details
Tool-only mode
The agent runner includes the Gmail MCP server:~/.gmail-mcp directory is mounted read-write into the container:
Channel mode
The Gmail channel polls for unread emails every 60 seconds:Troubleshooting
OAuth token expired
OAuth token expired
Re-authorize:Then rebuild and restart.
Container can't access Gmail
Container can't access Gmail
Verify the mount in Check container logs:
src/container-runner.ts:Emails not being detected (channel mode)
Emails not being detected (channel mode)
Check the filter query in Check logs for Gmail polling errors:
src/channels/gmail.ts. The default is:Gmail connection not working
Gmail connection not working
Test the MCP server directly:Should show MCP protocol handshake. If it errors, check:
~/.gmail-mcp/gcp-oauth.keys.jsonexists~/.gmail-mcp/credentials.jsonexists (run auth if missing)
Available Gmail tools
The MCP server provides these tools to your agent:| Tool | Description |
|---|---|
mcp__gmail__send_email | Send an email (to, subject, body) |
mcp__gmail__read_email | Read a specific email by message ID |
mcp__gmail__search_emails | Search emails using Gmail query syntax |
mcp__gmail__create_draft | Create a draft email |
mcp__gmail__list_labels | List all Gmail labels |
Example usage
Ask your agent:Removing Gmail
To remove the Gmail skill and revert to a Gmail-free setup:Find the merge commit
abc1234 Merge remote-tracking branch 'upstream/skill/gmail'.Next steps
Skills system
Learn more about how skills work
Add Telegram
Add Telegram support to your installation
Add Discord
Add Discord support to your installation