Gmail Integration - NanoClaw Pro

Overview

The Gmail integration can work in two modes:

Tool-only mode: Agent has Gmail tools (read, send, search, draft) available when triggered from other channels
Channel mode: Incoming emails can trigger the agent and receive automatic replies

Both modes use Google Cloud OAuth for authentication.

Installation

Run the /add-gmail skill in Claude Code:

/add-gmail

The skill will ask whether you want channel mode or tool-only mode, then guide you through setup.

Google Cloud Setup

Create GCP Project

Go to console.cloud.google.com
Create a new project or select an existing one

Enable Gmail API

Go to APIs & Services → Library
Search for “Gmail API”
Click Enable

Configure Consent Screen

Go to APIs & Services → OAuth consent screen
Choose External user type
Fill in:
- App name (e.g., “NanoClaw Gmail”)
- User support email (your email)
- Developer contact email (your email)
Click Save and Continue
Skip adding scopes (the library handles this)
Add yourself as a test user
Click Save and Continue

Create OAuth Credentials

Go to APIs & Services → Credentials
Click + CREATE CREDENTIALS → OAuth client ID
Application type: Desktop app
Name: anything (e.g., “NanoClaw Gmail Client”)
Click Create
Click DOWNLOAD JSON and save as gcp-oauth.keys.json

Configuration

Install OAuth Credentials

Copy the downloaded credentials to ~/.gmail-mcp/:

mkdir -p ~/.gmail-mcp
cp /path/to/downloaded/gcp-oauth.keys.json ~/.gmail-mcp/gcp-oauth.keys.json

Authorize Access

Run the authorization flow:

npx -y @gongrzhe/server-gmail-autoauth-mcp auth

This will:

Open your browser
Ask you to sign in to Google
Show an “app isn’t verified” warning (this is normal for personal OAuth apps)
Ask for Gmail permissions
Save credentials to ~/.gmail-mcp/credentials.json

If you see “This app isn’t verified” warning, click Advanced → Go to [app name] (unsafe). This is normal for personal OAuth apps that haven’t gone through Google’s verification process.

Rebuild Container

The Gmail integration requires rebuilding the agent container (for MCP server changes):

# Clear stale agent-runner copies
rm -r data/sessions/*/agent-runner-src 2>/dev/null || true

# Rebuild container
cd container && ./build.sh && cd ..

# Build and restart
npm run build
launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
systemctl --user restart nanoclaw  # Linux

Tool-Only Mode

In tool-only mode, the agent has these Gmail tools available:

Tool	Purpose
`mcp__gmail__get_profile`	Get Gmail account info
`mcp__gmail__list_labels`	List all Gmail labels
`mcp__gmail__search_emails`	Search emails with Gmail query syntax
`mcp__gmail__get_email`	Get full email content by ID
`mcp__gmail__send_email`	Send a new email
`mcp__gmail__create_draft`	Create a draft email

Example Usage

From any registered channel:

User: @Andy check my recent emails

Claude: [calls mcp__gmail__search_emails with query "is:unread newer_than:1d"]
        You have 3 unread emails from today:
        1. John Smith - Project update
        2. GitHub - PR review requested
        3. Calendar - Meeting reminder

User: @Andy reply to John and say I'll review by EOD

Claude: [calls mcp__gmail__send_email]
        Sent! John will receive your reply.

Channel Mode

In channel mode, the Gmail integration polls your inbox and triggers the agent when new emails arrive.

How It Works

Polling: Checks for unread emails every 60 seconds (configurable)
Filtering: By default, only emails in Primary inbox trigger the agent (Promotions, Social, Updates, Forums excluded)
Processing: Agent receives email content and can use Gmail tools to reply
Notification: Agent is notified in the main channel about new emails

Email Filtering

Default filter query:

is:unread category:primary

This means:

Only unread emails
Only emails in the Primary inbox category
Excludes Promotions, Social, Updates, and Forums

You can customize the filter query by modifying the searchQuery parameter in the GmailChannel constructor in src/channels/gmail.ts.

Thread Tracking

The channel tracks email threads to enable proper reply handling:

interface ThreadMeta {
  sender: string;           // Email address
  senderName: string;       // Display name
  subject: string;          // Email subject
  messageId: string;        // RFC 2822 Message-ID for In-Reply-To
}

When the agent sends a reply, it includes proper email headers for threading.

Email Notification Format

When a new email arrives, the agent receives:

[Email from John Smith <[email protected]>]
Subject: Project Update

Hi Andy,

Just wanted to give you a quick update on the project...

By default, the agent is instructed NOT to reply to emails automatically. Add instructions to groups/main/CLAUDE.md if you want different behavior.

Troubleshooting

OAuth Token Expired

Tokens expire after a period of inactivity. Re-authorize:

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

Gmail Connection Not Responding

Test the connection directly:

npx -y @gongrzhe/server-gmail-autoauth-mcp

This starts the MCP server in stdio mode. You should see:

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"..."}}

If you see errors, check:

Credentials exist: ls -la ~/.gmail-mcp/
Credentials are valid JSON: cat ~/.gmail-mcp/credentials.json | jq
OAuth keys are valid: cat ~/.gmail-mcp/gcp-oauth.keys.json | jq

Container Can’t Access Gmail

The container needs ~/.gmail-mcp mounted. Verify in src/container-runner.ts:

const gmailMcpDir = path.join(os.homedir(), '.gmail-mcp');
if (existsSync(gmailMcpDir)) {
  mounts.push(
    `-v`,
    `${gmailMcpDir}:/home/node/.gmail-mcp`
  );
}

Check container logs:

cat groups/main/logs/container-*.log | tail -50

Emails Not Being Detected (Channel Mode)

Check Filter Query

The default filter is is:unread category:primary. Emails in Promotions, Social, etc. are excluded.

Check Polling

Look for Gmail polling activity in logs:

tail -f logs/nanoclaw.log | grep -i gmail

Check Processed IDs

The channel tracks processed email IDs to avoid duplicates. If stuck, restart:

launchctl kickstart -k gui/$(id -u)/com.nanoclaw

“App isn’t verified” Warning

This is normal for personal OAuth apps. Click:

Advanced
Go to [app name] (unsafe)
Allow

The warning appears because you haven’t submitted the app for Google’s verification process (which is only needed for public apps).

Implementation Details

Dependencies

googleapis - Google APIs client library (channel mode only)
@gongrzhe/server-gmail-autoauth-mcp - MCP server with Gmail tools (both modes)

JID Format

Channel mode: gmail:<thread-id> (e.g., gmail:18a1b2c3d4e5f6g7)

Self-Registration Code (Channel Mode)

registerChannel('gmail', (opts: ChannelOpts) => {
  const credDir = path.join(os.homedir(), '.gmail-mcp');
  const keysPath = path.join(credDir, 'gcp-oauth.keys.json');
  const tokensPath = path.join(credDir, 'credentials.json');
  
  if (!existsSync(keysPath) || !existsSync(tokensPath)) {
    logger.warn('Gmail credentials not found. Run /add-gmail to set up.');
    return null;
  }
  
  return new GmailChannel(opts);
});

Polling Logic

async pollForMessages(): Promise<void> {
  const response = await this.gmail.users.messages.list({
    userId: 'me',
    q: 'is:unread category:primary',
    maxResults: 10,
  });
  
  for (const message of response.data.messages || []) {
    if (this.processedIds.has(message.id!)) continue;
    
    const fullMessage = await this.gmail.users.messages.get({
      userId: 'me',
      id: message.id!,
      format: 'full',
    });
    
    // Extract headers, body, and deliver to agent
    this.processMessage(fullMessage);
    this.processedIds.add(message.id!);
  }
}

Error Backoff

If polling fails, the interval increases exponentially:

const backoffMs = Math.min(
  this.pollIntervalMs * Math.pow(2, this.consecutiveErrors),
  30 * 60 * 1000  // Max 30 minutes
);

Removal

Tool-Only Mode

Remove ~/.gmail-mcp mount from src/container-runner.ts
Remove gmail MCP server from container/agent-runner/src/index.ts
Remove gmail from .nanoclaw/state.yaml
Clear stale agent-runner: rm -r data/sessions/*/agent-runner-src 2>/dev/null || true
Rebuild: cd container && ./build.sh && cd .. && npm run build
Restart service

Channel Mode

Delete src/channels/gmail.ts and src/channels/gmail.test.ts
Remove import './gmail.js' from src/channels/index.ts
Follow steps 1-6 from tool-only mode removal
Uninstall: npm uninstall googleapis

Next Steps

Channel Overview

Learn about the channel system

WhatsApp Channel

Set up WhatsApp integration

Overview

Getting Started

Core Features

Channels

Customization

Architecture

Deployment

​Overview

​Installation

​Google Cloud Setup

​Configuration

​Install OAuth Credentials

​Authorize Access

​Rebuild Container

​Tool-Only Mode

​Example Usage

​Channel Mode

​How It Works

​Email Filtering

​Thread Tracking

​Email Notification Format

​Troubleshooting

​OAuth Token Expired

​Gmail Connection Not Responding

​Container Can’t Access Gmail

​Emails Not Being Detected (Channel Mode)

​“App isn’t verified” Warning

​Implementation Details

​Dependencies

​JID Format

​Self-Registration Code (Channel Mode)

​Polling Logic

​Error Backoff

​Removal

​Tool-Only Mode

​Channel Mode

​Next Steps

Channel Overview

WhatsApp Channel

Build docs developers (and LLMs) love

Overview

Installation

Google Cloud Setup

Configuration

Install OAuth Credentials

Authorize Access

Rebuild Container

Tool-Only Mode

Example Usage

Channel Mode

How It Works

Email Filtering

Thread Tracking

Email Notification Format

Troubleshooting

OAuth Token Expired

Gmail Connection Not Responding

Container Can’t Access Gmail

Emails Not Being Detected (Channel Mode)

“App isn’t verified” Warning

Implementation Details

Dependencies

JID Format

Self-Registration Code (Channel Mode)

Polling Logic

Error Backoff

Removal

Tool-Only Mode

Channel Mode

Next Steps