add-gmail

Add Gmail Integration

This skill adds Gmail capabilities to NanoClaw. It can be configured in two modes:

1. Tool Mode - Agent can read/send emails, but only when triggered from WhatsApp
2. Channel Mode - Emails can trigger the agent, schedule tasks, and receive email replies

Initial Questions

Ask the user:

How do you want to use Gmail with NanoClaw?

Option 1: Tool Mode

- Agent can read and send emails when you ask it to

- Triggered only from WhatsApp (e.g., "@Andy check my email" or "@Andy send an email to...")

- Simpler setup, no email polling

Option 2: Channel Mode

- Everything in Tool Mode, plus:

- Emails to a specific address/label trigger the agent

- Agent replies via email (not WhatsApp)

- Can schedule tasks via email

- Requires email polling infrastructure

Store their choice and proceed to the appropriate section.

Prerequisites (Both Modes)

1. Check Existing Gmail Setup

First, check if Gmail is already configured:

ls -la ~/.gmail-mcp/ 2>/dev/null || echo "No Gmail config found"

If credentials.json exists, skip to "Verify Gmail Access" below.

2. Create Gmail Config Directory

mkdir -p ~/.gmail-mcp

3. GCP Project Setup

USER ACTION REQUIRED

Tell the user:

I need you to set up Google Cloud OAuth credentials. I'll walk you through it:

1. Open https://console.cloud.google.com in your browser

2. Create a new project (or select existing) - click the project dropdown at the top

Wait for user confirmation, then continue:

3. Now enable the Gmail API:

- In the left sidebar, go to APIs & Services → Library

- Search for "Gmail API"

- Click on it, then click Enable

Wait for user confirmation, then continue:

4. Now create OAuth credentials:

- Go to APIs & Services → Credentials (in the left sidebar)

- Click + CREATE CREDENTIALS at the top

- Select OAuth client ID

- If prompted for consent screen, choose "External", fill in app name (e.g., "NanoClaw"), your email, and save

- For Application type, select Desktop app

- Name it anything (e.g., "NanoClaw Gmail")

- Click Create

Wait for user confirmation, then continue:

5. Download the credentials:

- Click DOWNLOAD JSON on the popup (or find it in the credentials list and click the download icon)

- Save it as gcp-oauth.keys.json

Where did you save the file? (Give me the full path, or just paste the file contents here)

If user provides a path, copy it:

cp "/path/user/provided/gcp-oauth.keys.json" ~/.gmail-mcp/gcp-oauth.keys.json

If user pastes the JSON content, write it directly:

cat > ~/.gmail-mcp/gcp-oauth.keys.json << 'EOF'
{paste the JSON here}
EOF

Verify the file is valid JSON:

cat ~/.gmail-mcp/gcp-oauth.keys.json | head -5

4. OAuth Authorization

USER ACTION REQUIRED

Tell the user:

I'm going to run the Gmail authorization. A browser window will open asking you to sign in to Google and grant access.

Important: If you see a warning that the app isn't verified, click "Advanced" then "Go to [app name] (unsafe)" - this is normal for personal OAuth apps.

Run the authorization:

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

If that doesn't work (some versions don't have an auth subcommand), run it and let it prompt:

timeout 60 npx -y @gongrzhe/server-gmail-autoauth-mcp || true

Tell user:

Complete the authorization in your browser. The window should close automatically when done. Let me know when you've authorized.

5. Verify Gmail Access

Check that credentials were saved:

if [ -f ~/.gmail-mcp/credentials.json ]; then
  echo "Gmail authorization successful!"
  ls -la ~/.gmail-mcp/
else
  echo "ERROR: credentials.json not found - authorization may have failed"
fi

Test the connection by listing labels (quick sanity check):

echo '{"method": "tools/list"}' | timeout 10 npx -y @gongrzhe/server-gmail-autoauth-mcp 2>/dev/null | head -20 || echo "MCP responded (check output above)"

If everything works, proceed to implementation.

Tool Mode Implementation

For Tool Mode, integrate Gmail MCP into the agent runner. Execute these changes directly.

Step 1: Add Gmail MCP to Agent Runner

Read container/agent-runner/src/index.ts and find the mcpServers config in the query() call.

Add gmail to the mcpServers object:

gmail: { command: 'npx', args: ['-y', '@gongrzhe/server-gmail-autoauth-mcp'] }

Find the allowedTools array and add Gmail tools:

'mcp__gmail__*'

The result should look like:

mcpServers: {
  nanoclaw: ipcMcp,
  gmail: { command: 'npx', args: ['-y', '@gongrzhe/server-gmail-autoauth-mcp'] }
},
allowedTools: [
  'Bash',
  'Read', 'Write', 'Edit', 'Glob', 'Grep',
  'WebSearch', 'WebFetch',
  'mcp__nanoclaw__*',
  'mcp__gmail__*'
],

Step 2: Mount Gmail Credentials in Container

Read src/container-runner.ts and find the buildVolumeMounts function.

Add this mount block (after the .claude mount is a good location):

// Gmail credentials directory
const gmailDir = path.join(homeDir, '.gmail-mcp');
if (fs.existsSync(gmailDir)) {
  mounts.push({
    hostPath: gmailDir,
    containerPath: '/home/node/.gmail-mcp',
    readonly: false  // MCP may need to refresh tokens
  });
}

Step 3: Update Group Memory

Append to groups/CLAUDE.md (the global memory file):

## Email (Gmail)

You have access to Gmail via MCP tools:
- `mcp__gmail__search_emails` - Search emails with query
- `mcp__gmail__get_email` - Get full email content by ID
- `mcp__gmail__send_email` - Send an email
- `mcp__gmail__draft_email` - Create a draft
- `mcp__gmail__list_labels` - List available labels

Example: "Check my unread emails from today" or "Send an email to john@example.com about the meeting"

Also append the same section to groups/main/CLAUDE.md.

Step 4: Rebuild and Restart

Run these commands:

cd container && ./build.sh

Wait for container build to complete, then:

cd .. && npm run build

Wait for TypeScript compilation, then restart the service:

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

Check that it started:

sleep 2 && launchctl list | grep nanoclaw

Step 5: Test Gmail Integration

Tell the user:

Gmail integration is set up! Test it by sending this message in your WhatsApp god channel:

@Andy check my recent emails

Or:

@Andy list my Gmail labels

Watch the logs for any errors:

tail -f logs/nanoclaw.log

Channel Mode Implementation

Channel Mode includes everything from Tool Mode, plus email polling and routing.

Additional Questions for Channel Mode

Ask the user:

How should the agent be triggered from email?

Option A: Specific Label

- Create a Gmail label (e.g., "NanoClaw")

- Emails with this label trigger the agent

- You manually label emails or set up Gmail filters

Option B: Email Address Pattern

- Emails to a specific address pattern (e.g., andy+task@gmail.com)

- Uses Gmail's plus-addressing feature

Option C: Subject Prefix

- Emails with a subject starting with a keyword (e.g., "[Andy]")

- Anyone can trigger the agent by using the prefix

Also ask:

How should email conversations be grouped?

Option A: Per Email Thread

- Each email thread gets its own conversation context

- Agent remembers the thread history

Option B: Per Sender

- All emails from the same sender share context

- Agent remembers all interactions with that person

Option C: Single Context

- All emails share the god group context

- Like an additional input to the god channel

Store their choices for implementation.

Step 1: Complete Tool Mode First

Complete all Tool Mode steps above before continuing. Verify Gmai