Od jakiegoś czasu planowałem ogarnąć Google Workspace w moim setupie Claude Code. Miałem podpięty serwer MCP dla Gmaila i osobny dla Google Calendar przez integrację claude.ai. Oba działały, mniej więcej. Ale miały cały typowy narzut MCP: dwa kolejne procesy do startu, dwa kolejne wpisy w konfiguracji, dwa kolejne miejsca, gdzie coś może się posypać. I żaden nie dawał szczególnie czystego outputu do automatyzacji.

Dziś zastąpiłem oba jednym CLI o nazwie gws. To jeden z tych installi, gdzie spędzasz dziesięć minut na konfiguracji i od razu zastanawiasz się, czemu nie zrobiłeś tego wcześniej.

Czym właściwie jest gws

gws to Google Workspace CLI z GitHub org Google Workspace. Podstawowy pomysł jest niestandardowy: zamiast ręcznie pisać wrappery dla każdego API, narzędzie czyta Google Discovery Service przy starcie i dynamicznie buduje wszystkie komendy. Każdy serwis, który Google publikuje przez Discovery API, gws może wywołać.

Struktura komend mapuje się bezpośrednio na API:

1

gws <service> <resource> [sub-resource] <method> [options]

Czyli gws gmail users messages list to dokładnie endpoint messages.list z Gmail API. gws drive files get to files.get z Drive. Bez zgadywania konwencji nazewniczych, bez nieudokumentowanych metod. Jeśli API to ma, CLI to ma.

Serwisy, które obsługuje: Gmail, Calendar, Drive, Sheets, Docs, Tasks, People, Chat, Slides, Forms, Keep, Meet i kilka innych. Wszystko zwraca strukturalny JSON domyślnie.

Wersja, którą dziś zainstalowałem, to 0.9.1. Pre-1.0, ale radzi sobie ze wszystkim, co mu rzuciłem.

Dlaczego to ważne dla Claude Code

Wartość Claude Code rośnie, gdy może rzeczywiście coś robić. Czytanie kodu, pisanie kodu, to proste. Ale “sprawdź, czy mam coś ważnego w skrzynce” albo “dodaj przypomnienie do kalendarza” wymagają dostępu na zewnątrz.

Podejście MCP działa, ale dodaje warstwę. Każdy serwer MCP to osobny proces, który trzeba uruchomić, uwierzytelnić, utrzymać połączenie i wystawić schemat narzędzi. Konfiguruje się go w .mcp.json, osobno zarządza credentials, debuguje start serwera gdy coś się nie chce uruchomić. Ok dla jednego czy dwóch serwerów pokrywających unikalne możliwości. Dla Google Workspace, gdzie po prostu chcesz wywołać API, to więcej ceremonii niż zadanie wymaga.

Z gws wywołanie to zwykła komenda bash. A komendy bash w Claude Code są pierwszoklasowe. Wykonują się natychmiast, zwracają JSON na stdout i można je łączyć z jq dla dowolnych przekształceń. Nie ma schematu MCP do negocjowania, nie ma latencji startu serwera. Wzorzec auto-approve hooków, którego używam, obsługuje już komendy bash z zaufanych narzędzi.

Jak to wygląda w praktyce. Triage skrzynki, który wymagał wywołania narzędzia MCP, to teraz:

1

gws gmail +triage

Output to tabela nieprzeczytanych wiadomości z datą, nadawcą, ID i tematem. Czytelna dla człowieka, parsowalna dla Claude.

Komendy pomocnicze

Surowa powierzchnia API jest przydatna do automatyzacji, ale helpery +command to miejsce, gdzie dzieje się codzienna praca. To gotowe workflow, które obsługują boilerplate za ciebie.

Gmail helpers:

1
2
3
4
5
6
7
8

# Podsumowanie nieprzeczytanych
gws gmail +triage

# Wyślij email
gws gmail +send --to [email protected] --subject "Quick question" --body "..."

# Odpowiedź z automatyczną obsługą wątku (In-Reply-To, References, threadId)
gws gmail +reply --message-id 19cd5f49b05e7161 --body "Got it, thanks."

Helper +reply jest szczególnie dobry. Poprawne wątkowanie odpowiedzi w surowych wywołaniach Gmail API wymaga ręcznego ustawiania trzech nagłówków. Helper robi to za ciebie.

Calendar helpers:

1
2
3
4
5
6
7
8
9

# Nadchodzące wydarzenia (domyślnie okno na dziś)
gws calendar +agenda

# Utwórz wydarzenie
gws calendar +insert \
  --summary "Code review" \
  --start "2026-03-11T14:00:00+01:00" \
  --end "2026-03-11T14:30:00+01:00" \
  --attendee [email protected]

Drive helpers:

1
2

# Upload z automatycznym wykrywaniem MIME type
gws drive +upload ./report.pdf --parent FOLDER_ID

Sheets helpers:

1
2
3
4
5
6
7
8
9

# Odczyt zakresu
gws sheets +read --spreadsheet SHEET_ID --range "Sheet1!A1:D10"

# Dopisz wiersz
gws sheets +append --spreadsheet SHEET_ID --values "2026-03-10,passed,42ms"

# Wstaw wiele wierszy
gws sheets +append --spreadsheet SHEET_ID \
  --json-values '[["row1col1","row1col2"],["row2col1","row2col2"]]'

Dla wszystkiego poza zasięgiem helperów surowe endpointy API są o jedną komendę dalej.

Konfiguracja

Setup ma trzy części: instalacja, uwierzytelnienie i konfiguracja credentials do trwałego użycia.

Instalacja

1

npm install -g @googleworkspace/cli

To dodaje gws do PATH. Sprawdzenie czy działa:

1
2

gws --version
# gws 0.9.1

Klient OAuth

Potrzebujesz projektu Google Cloud ze skonfigurowanym klientem OAuth2. Kroki:

  1. Utwórz lub otwórz projekt w Google Cloud Console
  2. Włącz potrzebne API (Gmail API, Calendar API, Drive API, Sheets API, Docs API, Tasks API)
  3. Przejdź do APIs & Services > Credentials
  4. Utwórz OAuth 2.0 Client ID, typ “Desktop app”
  5. Pobierz JSON

Zapisz pobrany JSON jako ~/.config/gws/client_secret.json. Katalog może wymagać stworzenia:

1
2

mkdir -p ~/.config/gws
mv ~/Downloads/client_secret_*.json ~/.config/gws/client_secret.json

Wymiana tokenu

To jedyny krok, który nie jest automatyczny. Jeśli pracujesz na serwerze, czyli wszędzie bez przeglądarki wskazującej na localhost, standardowy redirect OAuth nie zadziała.

1
2
3
4
5

# Rozpocznij flow autoryzacji
gws auth login

# gws wypisuje URL, mniej więcej:
# https://accounts.google.com/o/oauth2/auth?...&redirect_uri=http://localhost:PORT/...

Otwórz ten URL w przeglądarce. Autoryzuj dostęp. Google przekierowuje na http://localhost:PORT/... z parametrem code. Redirect się nie powiedzie (nic nie nasłuchuje), ale URL w pasku adresu przeglądarki zawiera potrzebny kod.

Skopiuj pełny URL przekierowania z paska adresu. Potem wymień kod ręcznie:

1

gws auth exchange "http://localhost:PORT/callback?code=CODE&scope=..."

gws zapisuje credentials do ~/.config/gws/credentials.json. Gotowe.

Ten ręczny krok wymiany to jednorazowy setup. Potem gws odświeża token automatycznie.

Zabezpieczenie pliku credentials

Plik credentials ma dostęp do twojego konta Google. Warto go zbackupować do Vault:

1

vault kv put secret/services/google credentials="$(cat ~/.config/gws/credentials.json)"

Zastąpienie serwerów MCP

Przed dziś mój .mcp.json miał wpisy dla mcp__claude_ai_Gmail__* i mcp__claude_ai_Google_Calendar__* przez integrację MCP claude.ai. Teraz ich nie ma.

Gmail MCP wystawiał narzędzia takie jak gmail_list_messages, gmail_read_message, gmail_search_messages, gmail_create_draft. Calendar MCP wystawiał gcal_list_events, gcal_create_event, gcal_get_event. Wszystko to jest teraz bashem.

Czemu bash jest tu lepszy? Kilka powodów.

Format outputu jest bardziej przewidywalny. Output narzędzi MCP jest ustrukturyzowany pod kątem konsumpcji przez Claude, ale nie zawsze idealny do łączenia z innymi komendami. gws wypisuje czysty JSON, który można przekazać do jq dla dowolnej transformacji.

Model uprawnień jest prostszy. Mam już wzorzec auto-approve oparty na hookach dla zaufanych komend bash. Nie trzeba konfigurować osobnych reguł zatwierdzania MCP dla operacji Google.

Nie ma startu serwera. Serwery MCP dodają latencję przy starcie sesji. gws uruchamia się na żądanie.

Zakres jest szerszy. Jeśli potrzebuję operacji na Sheets, to to samo CLI. Tak samo dla Docs, Tasks, Drive. Serwery MCP pokrywały tylko te serwisy, dla których były zbudowane. gws pokrywa wszystko, co Google wystawia.

Dodałem główne komendy gws do reguł auto-approve hooków, żeby Claude mógł ich używać bez promptów podczas sesji. gws gmail +triage, gws calendar +agenda, gws sheets +read działają bez pytania. Operacje zapisu jak +send i +insert wymagają potwierdzenia.

Co to umożliwia

Kombinacja strukturalnego JSON outputu i bash-friendliness oznacza, że Claude Code może teraz orkiestrować Google Workspace jako część większych workflow bez żadnej infrastruktury MCP.

Kilka rzeczy, których użyłem od czasu konfiguracji dziś:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Sprawdź skrzynkę przed porannym briefingiem
gws gmail +triage | jq '.[] | select(.from | contains("important-domain.com"))'

# Odczyt konkretnej wiadomości
gws gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID","format":"full"}'

# Szukaj plików na Drive po dacie modyfikacji
gws drive files list --params '{"q":"modifiedTime > \"2026-03-01T00:00:00Z\"","orderBy":"modifiedTime desc"}'

# Odczyt arkusza śledzenia faktur
gws sheets +read --spreadsheet SHEET_ID --range "2026!A:F"

To ostatnie daje największą satysfakcję. Mam arkusz logujący każdą fakturę, którą otrzymuję. Wcześniej dostanie danych do środka lub na zewnątrz wymagało Rube MCP albo ręcznej pracy w przeglądarce. Teraz to jedna linia.

Kąt Discovery Service

Jedna rzecz warta wspomnienia: ponieważ gws jest dynamicznie budowany z Discovery Service, nie jest zamrożony na snapshocie API. Gdy Google dodaje nowe endpointy lub parametry, gws je pobiera. Możesz też sprawdzić, czego oczekuje dowolny endpoint przed wywołaniem:

1

gws schema gmail.users.messages.send --resolve-refs

To wypisuje pełny schemat JSON dla ciała żądania. Przy pisaniu payloadu --json dla złożonych wywołań jest to dużo szybsze niż czytanie dokumentacji API.

Czego nie zastępuje

gws obsługuje wywołania API. Nie zastępuje Rube MCP dla operacji LinkedIn (inny produkt) ani żadnego z innych serwerów MCP, które używam dla Jiry, Tavily czy Trigger.dev. Te pokrywają możliwości, które nie mają prostego odpowiednika w CLI.

I dla operacji Google Workspace wymagających interakcji z przeglądarką albo flow OAuth w imieniu innych użytkowników, gws nie jest właściwym narzędziem. Uwierzytelnia się jako ty, dla twojego konta. To pokrywa zdecydowaną większość tego, co faktycznie robię z Claude Code.

Dla wszystkiego wymagającego surowego API, gws schema plus flagi --json i --params dają radę. To nieco bardziej rozbudowane niż dedykowane narzędzie MCP, ale nigdy nie zabraknie ci pokrycia.

Post opisujący, jak to wszystko się ze sobą łączy: The 120-file Claude Code developer workbench. Hooki, które sprawiają, że auto-approve jest bezpieczny, opisałem w Claude Code hooks: building a safety layer. Jeśli dopiero zaczynasz z MCP i chcesz wiedzieć co zastąpiłem, What is MCP and how to set it up in Claude Code omawia podstawy protokołu.