gws-gmail-read Skill: What It Does and How to Install It

Lets Claude read one Gmail message by its ID and extract the body or headers as text or JSON, through the gws command-line tool.

Installs: 41.5K; on skills.sh
Stars: 32K; on GitHub
Updated: Oct 2026; last repo commit

gws-gmail-read gives Claude one command, gws gmail +read, which takes a Gmail message ID and prints the message body. Flags add headers (From, To, Subject, Date), JSON output, the HTML body, or a dry run that shows the request without sending it. HTML-only messages are converted to plain text automatically. It needs the gws program signed in to your Google account, and its first instruction is to read the gws-shared skill.

Good for

People who want Claude to read and summarise a specific email
Anyone building a mail workflow that starts from a message ID
Claude Code users who already use the gws CLI for Workspace

Install gws-gmail-read

Claude Code

Copy this prompt.

Install the gws-gmail-read skill in Claude Code. Run this command:

npm install -g @googleworkspace/cli
gws auth setup
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-shared
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail-read

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js 18+, A Google Cloud project, A Google account.

The README says gws is not an officially supported Google product and is under active development, so expect breaking changes. If Google consent shows "hasn't verified this app" while your OAuth app is in testing mode, the README says to continue.

From the project README. Source.

What's in the skill

When it loads

Gmail: Read a message and extract its body or headers.

Sections in SKILL.md

Usage
Flags
Examples
Tips
See Also

Key facts

Author: googleworkspace
Repository: googleworkspace/cli
License: Apache-2.0
Skill version: 0.22.5
Installs on skills.sh: 41,516 (Nov 2, 2026)
GitHub stars: 32,038 (Nov 2, 2026)
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk warn (Nov 2, 2026)
Last repo commit: Oct 30, 2026
Files: 1 file: SKILL.md only
Needs: The gws program (SKILL.md lists it as a required binary) and the gws-shared skill
Status: The README says gws is not an officially supported Google product

What it includes

Reads one Gmail message and prints its body as plain text
Converts HTML-only messages to plain text and handles multipart/alternative and base64 decoding.
Try: “Read Gmail message 18f1a2b3c4d and summarise it”
Network · gws gmail +read --id <ID>
Adds From, To, Subject and Date to the output
--headers
Chooses text (default) or json output
--format
Returns the HTML body instead of plain text
--html
Shows the request that would be sent without executing it
--dry-run

From the official docs

Permissions

Medium risk

It lets Claude read the full text of Gmail messages you point it at, and that text goes into your Claude conversation. Point it only at messages you are comfortable sharing with your AI provider.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It reads full email bodies and headers
The message text and headers are sent to your AI provider. Point it only at messages you are comfortable sharing that way.
Email text can try to steer Claude
A message can contain instructions written for an AI. Do not let Claude act on instructions found inside an email without checking with you.
Sign-in gives gws access to your mailbox
SKILL.md does not say which Gmail permission +read needs. The README shows how to choose services at sign-in, so pick Gmail only and read the consent screen.
The gws program is under active development
The README warns to expect breaking changes before v1.0. Pin the version you tested.

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only mode is documented. The --dry-run flag shows a request without sending it.
Talks to	The gws program calls Google Workspace APIs. Your AI provider receives the data Claude reads from Google
Sign-in and keys	Sign-in is handled by the gws program. The README says credentials are encrypted at rest (AES-256-GCM) with the key in your OS keyring, or in ~/.config/gws/.encryption_key when the file backend is set.
Scopes	Claude runs gws gmail +read on your machine gws signs in with your Google account and calls the Gmail API

Questions

How do I install gws-gmail-read?

Use the install box above. It installs the gws program, signs you in, and adds gws-shared and gws-gmail-read. SKILL.md also points to gws-gmail for send, read and manage commands.

How do I find the message ID?

SKILL.md says the --id flag takes the Gmail message ID and gives 18f1a2b3c4d as an example, but it does not say how to look one up. The gws-gmail skill that SKILL.md points to covers the wider set of Gmail commands.

Can gws-gmail-read send or delete mail?

This skill documents one command, gws gmail +read. SKILL.md points to the separate gws-gmail skill for send, read and manage commands.

Does it need an API key?

Not in the usual sense. The README requires a Google Cloud project for OAuth credentials and a Google account.

Does gws-gmail-read work in the Claude app?

The README documents no Claude app install. The skill drives a program on your machine, so use it in Claude Code or another local agent.

Is gws-gmail-read safe?

It reads private email and the text goes to your AI provider, so use it on messages you are comfortable sharing that way. Sign in with the narrowest Gmail permission the consent screen offers. The skill file is one SKILL.md and bundles no scripts.

Information

updated Nov 2, 2026

Repository: googleworkspace/cli
Folder: skills/gws-gmail-read

googleworkspace/cli skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 7

googleworkspace/cli README · github.com
gws-shared SKILL.md · github.com
googleworkspace/cli · github.com
skills CLI commands · github.com
gws-gmail-read SKILL.md · github.com
gws-gmail-read on skills.sh · skills.sh
gws-gmail SKILL.md · github.com