Help us improve
Share bugs, ideas, or general feedback.
From claudeclaw
Adds Gmail integration to ClaudeClaw as a tool (read/send/search/draft) or full channel (incoming emails trigger agent). Guides through GCP OAuth setup.
npx claudepluginhub sbusso/claudeclawHow this skill is triggered — by the user, by Claude, or both
Slash command
/claudeclaw:add-gmailThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill adds Gmail support to ClaudeClaw — either as a tool (read, send, search, draft) or as a full channel that polls the inbox.
Adds Gmail integration to NanoClaw: tool mode for agent read/send/search/draft emails or full channel mode for email-triggered agent responses and scheduling. Guides GCP OAuth setup and git merge.
Integrates Gmail with Claude Code via MCP for email processing: read, search, send, draft, manage labels, attachments, filters, and extract action items.
Guides Google Workspace CLI (gws) setup: installs via npm, creates GCP project, configures OAuth and APIs (Gmail/Drive/etc.), authenticates, installs Claude Code skills. For first-time use or auth troubleshooting.
Share bugs, ideas, or general feedback.
This skill adds Gmail support to ClaudeClaw — either as a tool (read, send, search, draft) or as a full channel that polls the inbox.
Check if src/channels/gmail.ts exists. If it does, skip to Phase 3 (Setup). The code changes are already in place.
Use AskUserQuestion:
AskUserQuestion: Should incoming emails be able to trigger the agent?
git remote -v
If gmail is missing, add it:
git remote add gmail https://github.com/qwibitai/claudeclaw-gmail.git
git fetch gmail main
git merge gmail/main || {
git checkout --theirs package-lock.json
git add package-lock.json
git merge --continue
}
This merges in:
src/channels/gmail.ts (GmailChannel class with self-registration via registerChannel)src/channels/gmail.test.ts (unit tests)import './gmail.js' appended to the channel barrel file src/channels/index.ts~/.gmail-mcp) in src/orchestrator/container-runner.ts@gongrzhe/server-gmail-autoauth-mcp) and mcp__gmail__* allowed tool in agent/runner/src/index.tsgoogleapis npm dependency in package.jsonIf the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
If the user chose channel mode, append the following to groups/main/CLAUDE.md (before the formatting section):
## Email Notifications
When you receive an email notification (messages starting with `[Email from ...`), inform the user about it but do NOT reply to the email unless specifically asked. You have Gmail tools available — use them only when the user explicitly asks you to reply, forward, or take action on an email.
npm install
npm run build
npx vitest run src/channels/gmail.test.ts
All tests must pass (including the new Gmail tests) and build must be clean before proceeding.
ls -la ~/.gmail-mcp/ 2>/dev/null || echo "No Gmail config found"
If credentials.json already exists, skip to "Build and restart" below.
Tell the user:
I need you to set up Google Cloud OAuth credentials:
- Open https://console.cloud.google.com — create a new project or select existing
- Go to APIs & Services > Library, search "Gmail API", click Enable
- 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., "ClaudeClaw Gmail")
- Click DOWNLOAD JSON and save as
gcp-oauth.keys.jsonWhere did you save the file? (Give me the full path, or paste the file contents here)
If user provides a path, copy it:
mkdir -p ~/.gmail-mcp
cp "/path/user/provided/gcp-oauth.keys.json" ~/.gmail-mcp/gcp-oauth.keys.json
If user pastes JSON content, write it to ~/.gmail-mcp/gcp-oauth.keys.json.
Tell the user:
I'm going to run Gmail authorization. A browser window will open — sign in and grant access. If you see an "app isn't verified" warning, 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 fails (some versions don't have an auth subcommand), try timeout 60 npx -y @gongrzhe/server-gmail-autoauth-mcp || true. Verify with ls ~/.gmail-mcp/credentials.json.
Clear stale per-group agent-runner copies (they only get re-created if missing, so existing copies won't pick up the new Gmail server):
rm -r data/sessions/*/agent-runner-src 2>/dev/null || true
Rebuild the container (agent-runner changed):
cd container && ./build.sh
Service name: Derived from the directory name:
com.claudeclaw.<dirname>(macOS) /claudeclaw-<dirname>(Linux). For example, if cwd ismy-assistant, the service iscom.claudeclaw.my-assistant. Determine the correct service name before running service commands below.
Then compile and restart:
npm run build
launchctl kickstart -k gui/$(id -u)/com.claudeclaw # macOS
# Linux: systemctl --user restart claudeclaw
Tell the user:
Gmail is connected! Send this in your main channel:
@Andy check my recent emailsor@Andy list my Gmail labels
Tell the user to send themselves a test email. The agent should pick it up within a minute. Monitor: tail -f logs/claudeclaw.log | grep -iE "(gmail|email)".
Once verified, offer filter customization via AskUserQuestion — by default, only emails in the Primary inbox trigger the agent (Promotions, Social, Updates, and Forums are excluded). The user can keep this default or narrow further by sender, label, or keywords. No code changes needed for filters.
tail -f logs/claudeclaw.log
Test directly:
npx -y @gongrzhe/server-gmail-autoauth-mcp
Re-authorize:
rm ~/.gmail-mcp/credentials.json
npx -y @gongrzhe/server-gmail-autoauth-mcp
~/.gmail-mcp is mounted: check src/orchestrator/container-runner.ts for the .gmail-mcp mountcat groups/main/logs/container-*.log | tail -50is:unread category:primary)~/.gmail-mcp mount from src/orchestrator/container-runner.tsgmail MCP server and mcp__gmail__* from agent/runner/src/index.tsrm -r data/sessions/*/agent-runner-src 2>/dev/null || truecd container && ./build.sh && cd .. && npm run build && launchctl kickstart -k gui/$(id -u)/com.claudeclaw (macOS) or systemctl --user restart claudeclaw (Linux)src/channels/gmail.ts and src/channels/gmail.test.tsimport './gmail.js' from src/channels/index.ts~/.gmail-mcp mount from src/orchestrator/container-runner.tsgmail MCP server and mcp__gmail__* from agent/runner/src/index.tsnpm uninstall googleapisrm -r data/sessions/*/agent-runner-src 2>/dev/null || truecd container && ./build.sh && cd .. && npm run build && launchctl kickstart -k gui/$(id -u)/com.claudeclaw (macOS) or systemctl --user restart claudeclaw (Linux)