mcpField
G
gmcli

gmcli

github.com/badlogicProductivity2.6k157 installsUpdated 21w ago
Repository

About gmcli

gmcli is a command-line interface for Gmail operations. It can search email, read conversation threads, send messages, and manage labels and drafts after OAuth account setup.

Key features

  1. 01Search email with Gmail query syntax
  2. 02Read all messages in a thread
  3. 03Send email
  4. 04List labels and drafts
  5. 05Configure OAuth accounts

Use cases

  1. 01Search for emails
  2. 02Review a full email thread
  3. 03Send email from the command line
  4. 04Inspect labels or drafts

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/badlogic/pi-skills --skill gmcli

After installing, type/gmcliin Claude Code to confirm it loaded.

Details

From the project README

Gmail CLI

Command-line interface for Gmail operations.

Installation

npm install -g @mariozechner/gmcli

Setup

Google Cloud Console (one-time)
  1. Create a new project (or select existing)
  2. Enable the Gmail API
  3. Set app name in OAuth branding
  4. Add test users (all Gmail addresses you want to use)
  5. Create OAuth client:
    • Click "Create Client"
    • Application type: "Desktop app"
    • Download the JSON file
Configure gmcli

First check if already configured:

gmcli accounts list

If no accounts, guide the user through setup:

  1. Ask if they have a Google Cloud project with Gmail API enabled
  2. If not, walk them through the Google Cloud Console steps above
  3. Have them download the OAuth credentials JSON
  4. Run: gmcli accounts credentials ~/path/to/credentials.json
  5. Run: gmcli accounts add <email> (use --manual for browserless OAuth)

Usage

Run gmcli --help for full command reference.

Common operations:

  • gmcli <email> search "<query>" - Search emails using Gmail query syntax
  • gmcli <email> thread <threadId> - Read a thread with all messages
  • gmcli <email> send --to <emails> --subject <s> --body <b> - Send email
  • gmcli <email> labels list - List all labels
  • gmcli <email> drafts list - List drafts

Data Storage

  • ~/.gmcli/credentials.json - OAuth client credentials
  • ~/.gmcli/accounts.json - Account tokens
  • ~/.gmcli/attachments/ - Downloaded attachments

Comments

Markdown supported