Skip to main content
The Add Gmail skill integrates Gmail into NanoClaw. You can choose tool-only mode (agent reads/sends emails when asked) or full channel mode (emails trigger the agent automatically).

​
What It Does

The Add Gmail skill:
  • Installs Gmail MCP server with read, send, search, draft tools
  • Sets up GCP OAuth credentials
  • Optionally installs Gmail channel for inbox monitoring
  • Configures email handling instructions

​
Prerequisites

  • NanoClaw base installation complete
  • Google account
  • Access to Google Cloud Console

​
How to Apply

1

Invoke the skill

Run /add-gmail in your NanoClaw context.
2

Choose mode

  • Tool-only: Agent can read/send emails but won’t monitor inbox
  • Channel mode: Emails trigger the agent (get forwarded to main channel)
3

Set up GCP OAuth

  1. Open https://console.cloud.google.com
  2. Create new project or select existing
  3. Go to APIs & Services > Library, enable Gmail API
  4. Go to APIs & Services > Credentials, create OAuth client ID
  5. Application type: Desktop app
  6. Download JSON and save as gcp-oauth.keys.json
4

Apply code changes

Tool-only:
  • Mounts ~/.gmail-mcp in container
  • Adds Gmail MCP server to agent-runner
Channel mode (applies all tool-only changes plus):
  • Adds src/channels/gmail.ts
  • Adds unit tests
  • Installs googleapis dependency
  • Appends email handling instructions to CLAUDE.md
5

Authorize Gmail access

Run OAuth flow:
npx -y @gongrzhe/server-gmail-autoauth-mcp auth
Sign in and grant access. If you see “app isn’t verified” warning, click Advanced → Go to [app name] (unsafe).
6

Rebuild container

Clear stale agent-runner copies and rebuild:
rm -r data/sessions/*/agent-runner-src 2>/dev/null || true
cd container && ./build.sh
npm run build

​
What Changes

​
Files Created

  • ~/.gmail-mcp/gcp-oauth.keys.json - GCP OAuth credentials
  • ~/.gmail-mcp/credentials.json - Gmail access token
  • src/channels/gmail.ts - Gmail channel (channel mode only)
  • src/channels/gmail.test.ts - Unit tests (channel mode only)

​
Files Modified

  • src/container-runner.ts - Mounts ~/.gmail-mcp in container
  • container/agent-runner/src/index.ts - Adds Gmail MCP server
  • groups/main/CLAUDE.md - Email handling instructions (channel mode)
  • package.json - Adds googleapis (channel mode only)
  • .nanoclaw/state.yaml - Records skill application

​
Usage

​
Tool-Only Mode

Ask the agent to interact with Gmail: 
You: Check my recent emails
Andy: [uses mcp__gmail__* tools to read inbox]

You: Send an email to [email protected] saying thanks
Andy: [uses mcp__gmail__send to send email]

​
Channel Mode

Incoming emails automatically trigger the agent:
  1. Email arrives in Primary inbox
  2. Agent receives notification: [Email from John: Subject line]
  3. Agent informs you in main channel
  4. You can ask agent to reply, forward, or take action
Default filter: Only Primary inbox emails trigger the agent (Promotions, Social, Updates, Forums are excluded).
In channel mode, the agent is instructed to inform you about emails but NOT reply unless specifically asked. This prevents unwanted auto-replies.

​
Troubleshooting

​
Gmail Connection Not Responding

Test directly: 
npx -y @gongrzhe/server-gmail-autoauth-mcp

​
OAuth Token Expired

Re-authorize: 
rm ~/.gmail-mcp/credentials.json
npx -y @gongrzhe/server-gmail-autoauth-mcp auth

​
Container Can’t Access Gmail

  • Verify ~/.gmail-mcp mount in src/container-runner.ts
  • Check container logs: cat groups/main/logs/container-*.log | tail -50

​
Emails Not Being Detected (Channel Mode)

Channel polls for is:unread category:primary by default. Check:
  • Logs for Gmail polling errors
  • Email is in Primary inbox (not Promotions/Social)
  • OAuth token is valid

​
Removal

​
Tool-Only Mode

  1. Remove ~/.gmail-mcp mount from src/container-runner.ts
  2. Remove Gmail MCP server from container/agent-runner/src/index.ts
  3. Clear agent-runner copies and rebuild

​
Channel Mode

  1. Delete src/channels/gmail.ts and src/channels/gmail.test.ts
  2. Remove import './gmail.js' from src/channels/index.ts
  3. Remove ~/.gmail-mcp mount from src/container-runner.ts
  4. Remove Gmail MCP server from container/agent-runner/src/index.ts
  5. Uninstall: npm uninstall googleapis
  6. Clear agent-runner copies and rebuild

Build docs developers (and LLMs) love

Get started for freeTalk to us