hermes-google

MCP server giving Hermes (Claude Code running as a personal assistant) scoped access to Gmail, Google Calendar, and Google Drive through a dedicated Hermes Google account — without granting access to your personal Google account.

See docs/superpowers/specs/2026-04-23-hermes-google-design.md for the full design.

Quick Start

Add hermes-google to your project's .mcp.json:

{
  "mcpServers": {
    "hermes-google": {
      "type": "stdio",
      "command": "uvx",
      "args": ["hermes-google-mcp@latest"]
    }
  }
}

Google Account Setup

1. Sign up for a plain Gmail account (e.g., hermes-yourname@gmail.com)
2. In Google Cloud Console: create a project, enable the Gmail, Calendar, and Drive APIs
3. Create an OAuth 2.0 Client ID (type: Desktop application) and download the client secret JSON
4. Save it as ~/.config/hermes-google/oauth_client.json
5. Run the setup script:

git clone https://github.com/jimmy-larsson/hermes-google.git
cd hermes-google
./scripts/setup.sh

The setup script creates the config, runs the OAuth flow (saving the token to ~/.config/hermes-google/token.json), and prints the remaining manual steps.

Host-Side OAuth

The OAuth flow opens a browser for consent — it must run on your host machine, not inside a headless container.

If your config and credentials live inside a container (e.g. Docker-mounted ~/.config/hermes-google/), you need to:

1. Copy config.toml and oauth_client.json to the host filesystem at ~/.config/hermes-google/
2. Run the OAuth flow from the host:

   uvx hermes-google-mcp@latest auth login
   

3. The resulting token.json is saved on the host — it will be picked up by the container through the volume mount

Gmail Setup

Create filters in your personal Gmail to route emails to the Hermes account:

1. For each sender you want Hermes to handle: create a filter that both labels the email (e.g. hermes-review) and forwards it to hermes-yourname@gmail.com — in a single filter
2. For replies from Hermes: from:hermes-yourname@gmail.com → apply label hermes

Gotchas

• Filters don't chain. Gmail evaluates all filters in a single pass against the original message properties. A label applied by filter A will not trigger filter B that matches on that label. You must combine label + forward into one filter per sender/criteria.
• "Apply to existing" skips forwarding. When you click "Also apply filter to matching conversations", Gmail only runs local actions (label, archive, star). Forwarding only fires on new incoming messages.

Calendar & Drive Setup

• Calendar: Share your calendar with the Hermes account at "Make changes to events" permission level. Set [user].calendar_id in config.toml.
• Drive: Share specific files/folders with the Hermes account. Optionally set [drive].default_parent_folder_id in config.toml for a default upload folder.

Usage

Once installed, the following tools are available to Hermes in every session:

• mail_list_pending, mail_search, mail_get, mail_send_draft, mail_mark_read, mail_archive
• cal_list_calendars, cal_list_events, cal_create_event, cal_update_event, cal_delete_event
• drive_search, drive_list, drive_get, drive_upload, drive_update, drive_move, drive_delete
• auth_status

All write operations require user confirmation. mail_send_draft is structurally restricted to your own email; it cannot send to external recipients.

Debug CLI

Same operations via shell:

hermes-google auth status
hermes-google mail list --limit 10
hermes-google mail get <message_id>
hermes-google cal list --start 2026-04-24T00:00:00+09:00 --end 2026-04-25T00:00:00+09:00
hermes-google drive search "Q1 report"

Revocation

Any one of these fully cuts an integration surface:

• Delete the forwarding filter in your personal Gmail
• Unshare your calendar with the Hermes account
• Unshare a Drive file or folder
• hermes-google auth revoke — removes the refresh token locally
• claude mcp remove hermes-google — Hermes loses the tools; Google data untouched
• Delete the Hermes Google account entirely

Development

conda activate hermes-google
pytest
ruff check src tests

Releasing

# 1. Bump version in pyproject.toml, commit and push
git commit -am "chore: bump version to X.Y.Z"
git push

# 2. Tag locally and push — triggers the CI pipeline
git tag X.Y.Z
git push origin X.Y.Z

# 3. After CI passes, create the GitHub release
gh release create X.Y.Z --verify-tag --generate-notes

Alternative Install Methods

# User scope — available in all your projects
claude mcp add -s user hermes-google -- uvx hermes-google-mcp

# Local scope — private to you in this project only
claude mcp add hermes-google -- uvx hermes-google-mcp