Read-only Gmail access for Hermes

Research memo on giving a local Hermes agent safe, read-only access to Gmail. Bottom line: the cleanest path is a local Google OAuth Desktop app using only gmail.readonly, exposed to Hermes as either a small read-only native tool or a locked-down local MCP server. OpenClaw has solved adjacent pieces, especially Gmail Pub/Sub wakeups and read-only Google Workspace plugin patterns.

Prepared May 2026Scope: Gmail read/search onlyPreferred: local-first OAuthAvoid: send/modify/delete scopes

Executive recommendation

Implement Hermes Gmail as a read-only local tool first, MCP second. Use Google’s official Gmail API with an OAuth Desktop client, request only https://www.googleapis.com/auth/gmail.readonly, store the refresh token locally under ~/.hermes with tight permissions, and expose only: labels, search, message get, thread get, attachment metadata/download-with-confirmation.

The installed Hermes google-workspace skill already has a read-only OAuth setup path for Gmail/Calendar/Contacts. However, its generic google_api.py still exposes write-capable commands. With a read-only token those should fail, but for defense-in-depth Hermes should add a dedicated gmail-readonly wrapper/toolset that simply has no send/modify/delete code paths.

Best path now

Use the existing Hermes Google Workspace setup, but wrap it with a read-only-only command surface.

fastest

Best external reference

taylorwilsdon/google_workspace_mcp has a strong read-only mode pattern.

copy pattern

Best OpenClaw lesson

OpenClaw’s Gmail Pub/Sub watcher is ideal for later “new important email” wakeups.

phase 2

Recommended architecture

Layer	Choice	Reason
Auth	Google OAuth Desktop app, user-owned Cloud project	No hosted broker; Connor controls client and token.
Scope	`gmail.readonly` only	Can view messages/settings; cannot send, modify labels, archive, delete.
Runtime	Local Python tool or stdio MCP server	Keeps token and mailbox data on the Hermes host.
Hermes surface	`gmail_search`, `gmail_get`, `gmail_thread`, `gmail_labels`	Small, auditable, no destructive verbs.
Safety	Audit log + body-size limits + confirmation for attachments/bulk reads	Gmail is sensitive even when read-only.
Phase 2	Gmail Pub/Sub watcher inspired by OpenClaw	Wake Hermes on new mail without polling.

Hermes current state

Installed skill: /root/.hermes/skills/productivity/google-workspace.
Current setup status: missing google_client_secret.json and google_token.json; not authenticated.
Current setup script scopes are already read-only: Gmail readonly, Calendar readonly, Contacts readonly.
Python Google deps are installed; gws CLI is not installed.
Issue: google_api.py still contains write-capable commands and broader scope constants. Scope prevents writes, but the UI/tool surface should also prevent them.

GSETUP="python /root/.hermes/skills/productivity/google-workspace/scripts/setup.py"
$GSETUP --client-secret /path/to/client_secret.json
$GSETUP --auth-url
$GSETUP --auth-code "FULL_REDIRECT_URL_OR_CODE"
$GSETUP --check

Minimal safe commands

GAPI="python /root/.hermes/skills/productivity/google-workspace/scripts/google_api.py"
$GAPI gmail labels
$GAPI gmail search "is:unread newer_than:7d" --max 10
$GAPI gmail get MESSAGE_ID

Do not rely on convention alone. Even if the token is read-only, Hermes should expose a separate read-only tool that has no parser routes for send/reply/modify/archive/delete.

Options compared

Option	Pros	Cons	Verdict
Native Hermes Gmail-readonly tool	Smallest surface; best prompt/tool names; easiest to enforce no writes.	Requires small implementation.	recommended
Existing Hermes Google Workspace skill + wrapper	Fastest; setup mostly exists.	Underlying CLI exposes write verbs; needs wrapper or patch.	short-term
Local Gmail MCP server	Reusable across clients; standard protocol.	Many public MCP servers request modify/send scopes.	good if locked down
Official Google Gmail MCP server	Official, maintained by Google.	Developer preview; remote hosted; scope config still needed.	watch
IMAP/App Password	Simple for email-only; no Cloud project.	Needs app passwords; less semantic than Gmail API; no Workspace future.	fallback
Composio/hosted connector	Very fast integration.	Third party sees/token-brokers mailbox access; broad action surface.	avoid for personal OS

OpenClaw findings

Official OpenClaw Gmail Pub/Sub watcher

OpenClaw core includes Gmail watcher hooks using Google Pub/Sub and gog/gogcli. It solves event-driven new-mail wakeups rather than full mailbox search/read. Useful phase-2 pattern for Hermes Commander Briefs and urgent-mail triggers.

github.com/openclaw/openclaw · docs.openclaw.ai Gmail Pub/Sub integration

tensorfold/openclaw-google-workspace

Best OpenClaw ecosystem pattern for scope minimization: it has a readOnly mode that maps to Gmail readonly scopes and gates write tools.

github.com/tensorfold/openclaw-google-workspace · ClawHub plugin page

gmail-no-send

Good safety model: explicitly excludes send endpoints and includes audit JSONL. It still supports draft/archive patterns, so Hermes should trim further for pure read-only.

github.com/meimakes/gmail-no-send · ClawHub page

Other OpenClaw Gmail tools

Several exist, but most include send/modify/archive or hosted broker surfaces: navbuildz/gmail-mcp-server, Thearthman/Openclaw_Gmail_Idle_Service, ethanbeard/openclaw-gws, mcinteerj/openclaw-gmail, Composio OpenClaw plugin.

Useful non-OpenClaw references

Gmail API scopes — official scope definitions; gmail.readonly is restricted.
Gmail API Python quickstart — InstalledAppFlow/token pattern Hermes can reuse.
OAuth 2.0 for native apps — desktop client flow.
Google official Gmail MCP server guide — remote MCP endpoint and OAuth setup.
taylorwilsdon/google_workspace_mcp — mature Google Workspace MCP with read-only mode.
psmolenski/gmail-mcp-readonly — tiny Dockerized read-only Gmail MCP server.
GongRzhe/Gmail-MCP-Server — popular but requests modify/write capabilities; useful as a cautionary reference.
Create a Gmail agent with MCP — example article, but not read-only-first.
Google API Services User Data Policy and restricted-scope verification — important if this becomes public/distributed.

Implementation contract for Hermes

Create gmail-readonly toolset or skill wrapper.
OAuth setup uses only gmail.readonly; fail closed if token contains broader scopes unless explicitly allowed.
Expose only read tools: labels, search, get message, get thread, attachment metadata; attachment download requires confirmation.
Store tokens in ~/.hermes/google_token.json or profile-specific Hermes home with 0600 permissions.
Log every Gmail tool call to a local audit JSONL with timestamp, query/message id, and byte count.
Hard cap message bodies and result counts by default; require explicit user approval for bulk export.
Add a future Pub/Sub watcher using OpenClaw’s pattern for “new important email” events.

Non-goals: no send, no reply, no mark-as-read, no archive, no labels, no delete, no hosted connector for personal mailbox access unless Connor explicitly chooses that tradeoff.