How to connect Gmail to Hermes Agent

Give Hermes Agent your Gmail without a Google Cloud project: search, read, draft and send, with read-only or per-action access and a history of every action.

Updated October 17, 2026

Short answer

Hermes Agent reaches Gmail two main ways on its own. Since v0.22.0, its hosted connectors reach Gmail through Nous's tool gateway after one browser sign-in. Its bundled Google Workspace skill reads and sends Gmail once you create a Google Cloud project and OAuth client. Neither documents a read-only mode or limits per action. For those, connect Gmail in Upsy, save Upsy in Hermes's config and run hermes mcp login upsy. It takes about five minutes and is free for personal use.

The built-in way

Hosted connectors

Hermes v0.22.0 added connectors: hosted apps such as Gmail that Hermes reaches through the Nous tool gateway. Ask Hermes for Gmail and open the sign-in link it returns. Without a Nous account, Hermes creates a free connectors-only identity on first use (Tool Search docs). You can add several named accounts, such as work and home, and manage them with /connectors or hermes connectors.

Where it stops: Nous's docs don't list the Gmail actions or describe a way to keep Hermes read-only, and the connection lives in Nous's gateway, for Hermes only. hermes connectors disconnect gmail removes an account.

The Google Workspace skill

google-workspace is bundled with Hermes and covers Gmail, Calendar, Drive, Contacts, Sheets and Docs. Its Gmail commands search, read, send, reply in the thread, and add or remove labels. They don't save drafts or download attachments.

Ask Hermes to "set up Google Workspace" and it walks you through the skill's steps: create a Cloud project, enable six APIs, create an OAuth client of type Desktop app, and add yourself as a test user while the app is in Testing (otherwise Google answers Error 403: access_denied). You give Hermes the client's JSON file, approve in the browser, and paste back the URL of the http://localhost:1 page that fails to load.

All or nothing. The setup script asks for one fixed set of permissions: read, send and modify mail, plus full Calendar, Drive, Sheets and Docs. The skill tells Hermes to confirm before sending, but that's an instruction to the model, not a limit on the token.
One account, in one token file, ~/.hermes/google_token.json.
A weekly sign-in on personal Gmail. A personal account needs an External consent screen, and while it's in Testing, Google's refresh tokens expire after 7 days.

For email only, the skill points to himalaya, another bundled skill, which uses IMAP and SMTP with a Gmail app password. Google offers those only with 2-Step Verification, often not on work accounts, and an app password can't be read-only.

Google's own Gmail MCP server

Google's Gmail MCP server is in a developer preview and can't send. As of October 2026, Hermes can't complete its sign-in (issue #137289), and hermes mcp catalog has no Gmail entry.

If you only use Hermes and don't need limits, the hosted connector is the quickest.

Where Upsy fits

Read-only that holds: Upsy doesn't list the tools that send, change or trash, and refuses them if called.
Pick actions, such as drafts and labels but no sending.
No Google Cloud project, and up to five Gmail accounts, each at its own level.
A history and alerts for everything Hermes does in your mail.
One connection for every assistant: the same Gmail in ChatGPT, Claude or Grok, each with its own access.

The same connection covers Google Calendar and Google Drive, Docs and Sheets. All guides are in the Hermes Agent hub.

What you need

Hermes Agent, set up with a model. We checked these steps against v0.22.2, released October 15, 2026.
A browser on the same machine for the sign-in. On a server, see Troubleshooting in the Google Calendar guide.
Gmail, personal or Google Workspace. On Workspace, your admin may have to allow the app.
A free Upsy account.

Connect Gmail to Hermes Agent

Create a free account at upsy.ai (Set up Upsy).
On the Apps page, click Connect an app, then Connect on Gmail. Upsy explains that Gmail connects through Composio for now. Click Continue, then sign in with the Google account you want Hermes to use.
Optional: click Add another account on Gmail for each other address, up to five.
Open Assistants, click Add assistant and pick Hermes under Which assistant?. Upsy shows the command with your address filled in.
In your terminal, save Upsy in Hermes's config without connecting yet:
```
hermes config set mcp_servers.upsy.url https://upsy.ai/connect && hermes config set mcp_servers.upsy.auth oauth
```
Use this rather than hermes mcp add, which connects before it saves and gives up on your sign-in after 30 seconds.
Run hermes mcp login upsy. Your browser opens "Hermes Agent wants to access your Upsy". Sign in, keep Gmail ticked, choose Read-only or All next to it, and click Allow. You have five minutes; once you're done, the terminal shows Authenticated — N tool(s) available.
Run hermes mcp test upsy to list the tools. In a Hermes chat that was already open, type /reload-mcp.
Upsy's page now shows Help Hermes Agent remember. Paste that message into Hermes so later sessions use Upsy for email without being told.

To allow only some Gmail actions, open Hermes Agent's page under Assistants, click Pick actions… next to Gmail, and tick what it may do. More on how Hermes handles MCP servers in how to add an MCP server to Hermes Agent.

Check that it works

Ask Hermes:

Use upsy to find emails from the last three days that ask me a question I haven't answered. List sender and subject.

Hermes calls mcp_upsy_search_threads (it names MCP tools mcp_<server>_<tool>), opens the threads and lists them. Upsy's History shows the search and each read under Hermes Agent.

What Hermes can do with Gmail

Tool	What it does	On Read-only
`search_threads`	Gmail search syntax, up to 50 threads a page	Yes
`get_message`, `email_read_thread`	One message, or a whole thread oldest first, with the list of attachments	Yes
`email_attachment`	Downloads an attachment of up to 10 MB	Yes
`email_labels`, `email_list_drafts`, `get_draft`	Your labels and drafts, and one draft's text	Yes
`create_draft`	A draft or a threaded reply, with up to 24 MB of files from Upsy or another email	No
`update_draft`	Changes a draft: recipients, subject, text or files. It stays in its thread	No
`send_message`	Sends mail: new, a reply in its thread, or a draft by its id	No
`email_send_draft`, `email_delete_draft`	Sends a draft as it is, or deletes it	No
`email_archive`, `email_update`	Archives; read or unread, star, important, labels	No
`email_trash`, `email_untrash`	Trash and restore. No tool deletes an email for good	No

New drafts and sent mail end with your Gmail signature, as when you write in Gmail.

Each Gmail account gets one level for Hermes: Full access, Read-only (the "Yes" rows), Pick actions or No access. With several accounts, each tool takes an account address; without one, Upsy uses the first account you connected. If Google Drive is connected too, drive_upload copies an attachment into Drive without the file passing through Hermes.

Hermes can also hide tools on its side, with a tools.exclude list under upsy in ~/.hermes/config.yaml (Hermes's MCP docs). Upsy's level still applies underneath, since Upsy checks it on every call.

Prompts to try

"Using upsy, list this month's emails from my bank and add up any amounts due."
"Read my thread with Omar about the contract and draft a reply asking for the signed PDF. Leave it as a draft."
"Archive every GitHub notification older than two weeks and mark them read."
"From my work address, reply to Lena's last email saying Thursday works."
"Every weekday at 8:00, summarize what reached my inbox overnight." Hermes schedules it.

Troubleshooting

"Connecting to MCP server 'upsy' timed out after 30s"

That's hermes mcp add giving up on the sign-in. If you then answered yes to "Save config anyway (you can test later)?", Upsy was saved turned off. Turn it on and sign in with the five-minute wait (more in the MCP server guide):

hermes config set mcp_servers.upsy.enabled true
hermes mcp login upsy

While Google reviews Upsy's own Google app, Gmail signs in through Composio's verified one, so Google's screen says Composio and asks for full mail access. That's expected and temporary. On a work account, your admin may first have to allow that app.

Hermes uses its own Gmail connector or skill

With several ways to Gmail, Hermes picks one. Say "use the upsy tools", or paste the remember message from setup so it prefers Upsy. To switch Hermes's hosted connectors off altogether, run hermes config set tools.connectors.enabled false.

Hermes says it has no tool to send

Gmail is on Read-only for Hermes, or you changed its level after the session started. Hermes keeps the tool list it got when it connected, so run /reload-mcp after any change in Upsy. If a tool answers "The user hasn't allowed you to use Gmail", Gmail is off for Hermes on its page in Upsy.

Security and privacy

Hermes never holds a Google token, only an Upsy one in ~/.hermes/mcp-tokens/upsy.json. The skill keeps a Google token with full mail access in ~/.hermes/google_token.json.
No prompt before sending. Hermes's approval prompts cover dangerous terminal commands; its docs describe none for MCP tools, and Upsy has no approval step. If Hermes must never send, choose Read-only, or leave sending out under Pick actions.
Emails can carry instructions aimed at agents. On Read-only, a hostile email can't get Hermes to send or trash anything through Upsy.
History lists each action under Hermes Agent with short details, like a sent email's subject and recipients. Neither Upsy nor Composio keeps your mail.
Alerts email you when one assistant sends 20 or more emails, trashes or deletes 50 or more items, or reads from your apps 100 or more times within 10 minutes.
Turning it off: set Gmail to No access, or click Remove Hermes Agent on its page in Upsy. hermes mcp remove upsy takes Upsy out of Hermes's config.

FAQ

Does Hermes Agent have a Gmail integration?

Yes, two: a hosted Gmail connector through Nous's tool gateway (since v0.22.0) and the bundled google-workspace skill. Upsy adds read-only and per-action access, a history and alerts.

Is there an email skill for Hermes Agent?

Yes: google-workspace (Gmail's API) and himalaya (IMAP and SMTP). A third, email-inbox-triage, sorts an inbox with one of them. Hermes's Email gateway is something else: it lets people email Hermes, from an account dedicated to it.

Does Hermes need a Google Cloud project for Gmail?

Only for the google-workspace skill or Google's own MCP server. Not for the hosted connector or Upsy.

Can Hermes Agent send email from Gmail?

Yes. The skill sends and replies. Through Upsy, Hermes sends when Gmail is on Full access, or on Pick actions with sending ticked.

Can I connect two Gmail accounts to Hermes?

Yes. Hosted connectors take several named accounts, and Upsy up to five, each at its own level. Without an address, Upsy uses the first account you connected. The skill holds one.