gmcp 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 41a8dfb444f066d7a4e2c51860bbefa84639ccb4ed7fdf6f7f4ed2186e0a7a45
+  data.tar.gz: 1c130067070a75a5c21402b72e57be49a5fff07bf30e86142ea84cfdbb7e8639
+SHA512:
+  metadata.gz: e6bb96b8b7a0bf91d9732f262af4f2df4ccfb0103dcd621f2a6c4c4ab13cfc6ec840ddd9764bc32f612ad15d2e5c18cdbf2fd8c8eccfe3db297958b96adc5b0b
+  data.tar.gz: 72df437e3f879a56c909bb1beb1c8d5daaab939b5e7e9663073c91b7b9aec1ccd8b06bfc5f0c33e93e696878963242eaf6364badc95b29edaf22675be8b90d70

data/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project are documented here.
+This project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.5.0]
+
+### Fixed
+
+- Access tokens refresh while the server runs; calls no longer start failing after an hour.
+- Failed Google API calls return an error instead of reporting success.
+- Every tool reports failures as an MCP error with the cause.
+- Token files are owner-only, and none are created for accounts that were never authorized.
+- The OAuth callback listens on loopback only and requires the flow's `state`.
+- `gmcp_authorize` accepts only accounts in `GMCP_ACCOUNTS`.
+- `bin/gmcp-auth` reports a failed authorization immediately.
+- `gmail_reply` threads correctly and answers `Reply-To`.
+- Outgoing mail rejects header injection and encodes non-ASCII subjects and names.
+- `calendar_rsvp` works, and honors `calendar_id`.
+- Calendars whose ids contain `#` (holidays, contacts) are reachable.
+- `calendar_get_event` honors `calendar_id`.
+- `drive_read_file` reads Docs, Sheets and Slides (exported as text or CSV) and plain text files.
+- `voice_list` and `voice_search` work on the current Voice API.
+- A rejected Voice session recovers on the next call.
+
+### Changed
+
+- `gmail_search` returns date, sender and subject for each message.
+- `gmail_list_attachments` returns a `part_id`; downloads keep their filenames.
+- `calendar_list_events` defaults to upcoming events and shows readable start times.
+- Calendar events accept `YYYY-MM-DD` for all-day events and an optional `time_zone`; attendees receive invitations.
+- `calendar_list_events`, `drive_search` and `drive_list_folder` return a `page_token` when more results exist.
+- Drive search and listing include shared drives.
+- Voice reads its session from the Chrome profile signed in as the account. Voice tools take `account:` and are limited to `GMCP_ACCOUNTS`. No Safari or Full Disk Access needed.
+- `voice_mark_read` takes a `thread_id`.
+
+### Removed
+
+- `voice_archive`, `voice_delete` and the `voice.trash` capability.
+- Safari cookie support.
+
+## [0.4.0]
+
+### Fixed
+
+- `gmail_get_message` and `calendar_get_event` return the record instead of an object id.
+- Message bodies decode to UTF-8 using the part's declared charset.
+
+### Added
+
+- `gmail_get_message` returns decoded headers and body text.
+- `Gmail::Message#headers`, `#header`, `#body_text` and `#to_summary`.
+
+### Changed
+
+- `him` resolves from RubyGems, so `gem install gmcp` works.
+
+## [0.3.1]
+
+### Fixed
+
+- Setup instructions register the server with `claude mcp add` and use `GMCP_ACCOUNTS`.
+
+### Added
+
+- README covers publishing the OAuth app, which avoids weekly re-authorization.
+
+## [0.3.0]
+
+### Fixed
+
+- One process serves several accounts safely; concurrent calls for different accounts no longer interfere.
+
+## [0.2.0]
+
+### Added
+
+- Capability scoping with `GMCP_CAPABILITIES`; ungranted tools are never registered.
+- Gmail pagination, batch archive/trash/modify, attachments and one-click unsubscribe.
+- Google Voice support (macOS).
+- `bin/gmail_survey`, a read-only per-sender inbox survey.
+- `GMCP_CREDENTIALS_FILE` to override the `credentials.json` location.
+
+### Changed
+
+- `bin/gmcp` prints its accounts and capabilities at startup.
+- `gmcp_authorize` pre-selects the requested account on the consent screen.
+
+### Fixed
+
+- A revoked refresh token no longer stops the server from starting.
+- `bin/gmcp-auth` works with Google's current OAuth flow.
+
+## [0.1.0]
+
+- Gmail, Calendar and Drive tools.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Twilight Coders LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,248 @@
+# GMCP
+
+Google Workspace MCP server (Gmail, Calendar, Drive) for Claude Code.
+
+Built on [`him`](https://github.com/TwilightCoders/him) (REST ORM), the
+[official Ruby MCP SDK](https://github.com/modelcontextprotocol/ruby-sdk),
+and Google's OAuth2 library (`googleauth`).
+
+## Why
+
+The built-in claude.ai Gmail/Calendar connectors have limited OAuth scopes —
+no trash, no labels, no send, no Drive access. GMCP runs as a local stdio MCP
+server with full `gmail.modify`, `calendar.events`, and `drive.readonly` scopes.
+
+## Tools
+
+**Gmail (9 tools)**
+`gmail_search`, `gmail_get_message`, `gmail_list_labels`, `gmail_trash_message`,
+`gmail_archive_message`, `gmail_label_message`, `gmail_send`, `gmail_create_draft`, `gmail_reply`
+
+**Calendar (7 tools)**
+`calendar_list_calendars`, `calendar_list_events`, `calendar_get_event`,
+`calendar_create_event`, `calendar_update_event`, `calendar_delete_event`, `calendar_rsvp`
+
+**Drive (3 tools)**
+`drive_search`, `drive_list_folder`, `drive_read_file`
+
+## Setup
+
+### 1. Google Cloud project
+
+1. Go to <https://console.cloud.google.com/>
+2. Create a project (or use an existing one)
+3. Enable the Gmail, Google Calendar, and Google Drive APIs
+4. Under **APIs & Services → Credentials**, create an OAuth 2.0 Client ID
+   - Application type: **Desktop app**
+5. Download the JSON file and save it to `~/.config/gmcp/credentials.json`
+6. Under **Google Auth Platform → Audience**, click **Publish app**
+
+Step 6 is not optional for day-to-day use. While the consent screen is in
+**Testing**, Google expires every refresh token after **7 days**, so each account
+silently stops working about a week after you authorize it and the server reports
+`invalid_grant`. Publishing to **In production** removes that expiry.
+
+Publishing is not the same as verification. An unverified production app still
+shows a "Google hasn't verified this app" interstitial (**Advanced → Go to …**)
+on each authorization, and is capped at 100 users. Full verification of the
+restricted `gmail.modify` scope requires an annual third-party security
+assessment, which is not worth doing for a personal install — accept the
+interstitial.
+
+
+### 2. Install
+
+```bash
+gem install gmcp
+```
+
+Or from source:
+```bash
+git clone https://github.com/TwilightCoders/GMCP ~/.gmcp
+cd ~/.gmcp && bundle install
+```
+
+### 3. Wire up Claude Code
+
+MCP servers are configured in `.claude.json`, not `settings.json`. Let the CLI
+write it so it lands in the config directory your sessions actually read
+(`$CLAUDE_CONFIG_DIR/.claude.json` when that is set, `~/.claude.json` otherwise):
+
+```sh
+GMCP=~/.gmcp   # wherever you cloned it
+
+claude mcp add gmcp --scope user \
+  --env "GMCP_ACCOUNTS=you@example.com,work@example.com" \
+  --env "GMCP_CAPABILITIES=gmcp.authorize,gmail.read,calendar.read,drive.read" \
+  --env "BUNDLE_GEMFILE=$GMCP/Gemfile" \
+  -- "$(which ruby)" "$GMCP/bin/gmcp"
+```
+
+`--scope user` registers it for every session on the machine; `--scope project`
+writes a `.mcp.json` next to a single repo, which is how you give one project a
+wider grant than the default (see **`GMCP_CAPABILITIES`** below).
+
+If you use a Ruby version manager, point the command at its shim rather than a
+versioned binary, so a Ruby upgrade does not silently break every session. With
+`rbenv`, add `--env "RBENV_DIR=$GMCP"` and the shim resolves the version from
+GMCP's own `.ruby-version`, regardless of which directory the session runs in.
+
+Verify with `claude mcp get gmcp`. On startup the server prints its accounts and
+capabilities to stderr — that stderr is the only place an operator can see what a
+given process was actually granted.
+
+### 4. Authorize from Claude
+
+Ask Claude to call `gmcp_authorize`, or run `bin/gmcp-auth <account>` from a terminal. Either opens your browser and captures the redirect on a temporary local callback server — there is nothing to copy and paste. (Google retired the out-of-band code flow in 2022.)
+
+Tokens are stored owner-only at `~/.config/gmcp/<account>/token.yaml`, and access tokens refresh automatically while the server runs. If a refresh token is revoked, the server still starts — the account is left unbound and reports that it needs re-authorizing, rather than taking the whole server down.
+
+## Multiple accounts and capability scoping
+
+GMCP is scoped along two independent axes. Both are environment variables read
+once at process start, so a given `bin/gmcp` process has a fixed, inspectable
+reach — it prints both to stderr on startup.
+
+### `GMCP_ACCOUNTS` — which mailboxes
+
+Comma-separated. Each account keeps its own OAuth token at
+`~/.config/gmcp/<account>/token.yaml`, and every Gmail/Calendar/Drive tool takes
+an optional `account:` argument selecting among them (defaulting to the first).
+
+```sh
+GMCP_ACCOUNTS=personal@example.com,work@example.com bin/gmcp
+```
+
+Authorize each one separately with `gmcp_authorize(account: "...")`.
+
+### `GMCP_CAPABILITIES` — which verbs
+
+Comma-separated capability names from `config/capabilities.yml`. Capabilities
+gate **registration**: a tool whose capability was not granted is never defined
+on the MCP server, so it never appears in `tools/list` and cannot be called no
+matter what the client sends.
+
+```sh
+# a read-only assistant
+GMCP_CAPABILITIES=gmail.read,calendar.read bin/gmcp
+
+# one that may also send
+GMCP_CAPABILITIES=gmail.read,gmail.send bin/gmcp
+```
+
+| Capability | Grants |
+|---|---|
+| `gmcp.authorize` | Start the OAuth flow (opens a browser) |
+| `gmail.read` | Search (paginated), read, list labels, list attachments, inspect unsubscribe options |
+| `gmail.modify_labels` | Add/remove labels and archive, single or batched (archiving *is* removing `INBOX`) |
+| `gmail.trash` | Trash a message, single or batched |
+| `gmail.send` | Send, draft, reply |
+| `gmail.download` | Write attachment bytes to a local directory |
+| `gmail.unsubscribe` | RFC 8058 one-click unsubscribe — leaves Google, tells a third party the address is live |
+| `calendar.read` | List calendars, read events |
+| `calendar.write` | Create, update, RSVP |
+| `calendar.delete` | Delete an event |
+| `drive.read` | Search, list folders, read files |
+| `voice.read` | List/search Voice; report an account's Voice number |
+| `voice.modify` | Mark a conversation read |
+
+`config/capabilities.yml` is the source of truth; a spec asserts it matches the
+tools actually registered, so it cannot silently drift.
+
+### Bulk work
+
+`gmail_search` returns one line per message (id, date, sender, subject) and
+paginates. It returns a `page_token` whenever more results exist; pass it back
+to walk a whole mailbox. `calendar_list_events`, `drive_search` and
+`drive_list_folder` page the same way. In Ruby, `Message.each_page` handles the
+cursor for you and is bounded by `max_pages` so a runaway cursor cannot spin.
+
+```ruby
+GMCP::Gmail::Message.each_page('in:inbox', max_results: 500) do |page|
+  page[:messages].each { |m| ... }
+end
+```
+
+Acting on the result is batched — `gmail_batch_archive`, `gmail_batch_trash`,
+and `gmail_batch_modify` take up to 1000 ids in one request rather than one
+round trip per message. Gmail returns nothing per-message, so a partial failure
+is not distinguishable; re-read if you need per-message confirmation.
+
+Attachments are two steps: `gmail_list_attachments` (under `gmail.read`) gives
+you filenames and `part_id`s, `gmail_download_attachment` (under
+`gmail.download`) writes one to a directory you name. There is no default destination, the
+filename is reduced to a basename so it cannot escape that directory, and an
+existing file is never overwritten.
+
+### Contract: unset and empty mean opposite things
+
+This distinction is the whole security boundary. It is not a convenience.
+
+| Value | Meaning |
+|---|---|
+| `GMCP_CAPABILITIES` **not set** | **Every** capability. For a human running `bin/gmcp` by hand with no grant system in front of it. |
+| `GMCP_CAPABILITIES=""` | **No** capabilities. The explicit empty grant set for an identity that was granted nothing. |
+
+**An automated launcher must always set the variable explicitly, including when
+the grant set is empty.** Omitting the key because there are no grants fails
+open and hands the process everything. There is no wildcard value, and unknown
+entries are dropped rather than trusted, so a grant cannot widen itself by typo.
+
+### Account isolation
+
+Models are bound to a *resolver*, not to a concrete API: `him` calls `use_api`
+at request time if it responds to `:call`, so `GMCP::ApiBinding` installs a
+lambda once and swaps the account per fiber via `Thread.current`.
+`Server.with_account` scopes a binding to a block and restores whatever was
+bound before, so two concurrent tool calls for different accounts cannot see
+each other's APIs, and a nested call cannot leak its account to its caller.
+
+A request with nothing bound raises `ApiBinding::NotBound` rather than falling
+back to whichever account the previous caller happened to leave behind.
+
+This was not always true. Until 0.3.0 the account was written onto the model
+class itself, so isolation depended on never running two requests at once —
+which is not isolation, only an absence of opportunity. Per-process separation
+was the recommendation because it was the only thing that actually held.
+
+**Capability separation is still per-process**, because `GMCP_CAPABILITIES` is
+read once at startup and decides which tools get registered at all. One process
+per capability set; that process may now serve several accounts safely.
+
+### Connectors and account scoping
+
+GMCP models `gmail`, `google_calendar`, `drive`, and `voice` as separate
+connectors, served by one process. Each declares in `config/capabilities.yml`
+whether `GMCP_ACCOUNTS` constrains it and where its credential lives:
+
+| Connector | `account_scoping` | `credential_source` | `GMCP_ACCOUNTS` constrains it? |
+|---|---|---|---|
+| `gmcp` | `enforced` | `local_file` | yes |
+| `gmail` | `enforced` | `local_file` | yes |
+| `google_calendar` | `enforced` | `local_file` | yes |
+| `drive` | `enforced` | `local_file` | yes |
+| `voice` | `enforced` | `delegated` (Chrome) | yes |
+
+Voice has no usable OAuth path — the token-to-cookie exchange is reserved for
+Chromium — so `GMCP::Voice::Session` uses the Google session of the **Chrome
+profile signed in as the requested account**, found by email in Chrome's profile
+list. Voice tools take `account:` like the rest and are limited to
+`GMCP_ACCOUNTS`; an account with no Chrome profile has no Voice. Chrome keeps
+the session fresh as you use it, so there is no separate sign-in.
+
+Chrome encrypts its cookies with a key in the macOS Keychain ("Chrome Safe
+Storage"). The first Voice call asks for access; choose **Always Allow**.
+Voice is macOS-only for that reason.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec
+```
+
+Ruby 3.4.9+ required.
+
+## License
+
+MIT. See `LICENSE.txt`.

data/bin/gmail_survey

@@ -0,0 +1,167 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Read-only Gmail survey. Pages through messages matching a query, fetches
+# minimal metadata (From, Subject, List-Unsubscribe, label IDs, internalDate)
+# for each, and aggregates into per-sender stats.
+#
+# Usage: bin/gmail_survey [--query "<gmail query>"] [--limit N] [--out PATH]
+#
+# Defaults to a broad sample so we can spot the bulk-win senders quickly.
+
+# Bundler only in a checkout; an installed gem resolves through RubyGems.
+require 'bundler/setup' if File.exist?(File.expand_path('../Gemfile', __dir__))
+require_relative '../lib/gmcp'
+require 'json'
+require 'optparse'
+require 'time'
+
+# Unbuffered so progress is visible when stdout is a pipe, not just a TTY.
+$stdout.sync = true
+
+options = {
+  query:   '',           # all mail
+  limit:   3000,
+  out:     'gmail_survey.json',
+  account: ENV['GMCP_ACCOUNT'] || ENV['GMCP_ACCOUNTS']&.split(',')&.first&.strip
+}
+OptionParser.new do |o|
+  o.on('--query Q')   { |v| options[:query]   = v }
+  o.on('--limit N')   { |v| options[:limit]   = v.to_i }
+  o.on('--out PATH')  { |v| options[:out]     = v }
+  o.on('--account A') { |v| options[:account] = v }
+end.parse!
+
+abort 'No account configured (set GMCP_ACCOUNT or pass --account)' unless options[:account]
+
+conn = GMCP::Apis.build_for_account(account: options[:account])[:gmail].connection
+
+def extract_email(from_header)
+  return nil unless from_header
+  m = from_header.match(/<([^>]+)>/) || from_header.match(/(\S+@\S+\.\S+)/)
+  m ? m[1].downcase : from_header.strip.downcase
+end
+
+def extract_domain(email)
+  email.to_s.split('@', 2)[1]&.downcase
+end
+
+# Faraday collapses repeated `metadataHeaders` params, so we ask for full
+# metadata format and just pick the headers we need. Slightly larger payload
+# but predictable.
+def metadata_url(id)
+  "messages/#{id}?format=metadata"
+end
+
+# 1. Page through messages.list collecting IDs.
+ids = []
+page_token = nil
+batch = 0
+loop do
+  batch += 1
+  params = { maxResults: 500 }
+  params[:q] = options[:query] unless options[:query].empty?
+  params[:pageToken] = page_token if page_token
+  body = conn.get('messages', params).body
+  data = body[:data] || body['data'] || body
+  msgs = data[:messages] || data['messages'] || []
+  ids.concat(msgs.map { |m| m[:id] || m['id'] })
+  page_token = data[:nextPageToken] || data['nextPageToken']
+  print "\rlisting: #{ids.length} ids in #{batch} pages..."
+  break if page_token.nil? || ids.length >= options[:limit]
+end
+ids = ids.first(options[:limit])
+puts "\nlisted #{ids.length} message IDs"
+
+# 2. Fetch metadata for each.
+records = []
+ids.each_with_index do |id, i|
+  body = conn.get(metadata_url(id)).body
+  data = body[:data] || body['data'] || body
+  payload = data[:payload] || data['payload'] || {}
+  hdrs    = payload[:headers] || payload['headers'] || []
+  pick    = lambda do |name|
+    h = hdrs.find { |hh| (hh[:name] || hh['name']).to_s.downcase == name.downcase }
+    h && (h[:value] || h['value'])
+  end
+
+  from        = pick.call('From')
+  subject     = pick.call('Subject')
+  list_unsub  = pick.call('List-Unsubscribe')
+  email       = extract_email(from)
+  domain      = extract_domain(email)
+  labels      = data[:labelIds] || data['labelIds'] || []
+  ts_ms       = (data[:internalDate] || data['internalDate']).to_i
+
+  records << {
+    id:           id,
+    from:         from,
+    email:        email,
+    domain:       domain,
+    subject:      subject&.[](0, 120),
+    has_list:     !list_unsub.nil?,
+    labels:       labels,
+    is_unread:    labels.include?('UNREAD'),
+    in_inbox:     labels.include?('INBOX'),
+    in_trash:     labels.include?('TRASH'),
+    in_spam:      labels.include?('SPAM'),
+    is_promo:     labels.include?('CATEGORY_PROMOTIONS'),
+    is_update:    labels.include?('CATEGORY_UPDATES'),
+    is_social:    labels.include?('CATEGORY_SOCIAL'),
+    ts_ms:        ts_ms,
+    ts_iso:       ts_ms.positive? ? Time.at(ts_ms / 1000).utc.iso8601 : nil
+  }
+
+  if (i + 1) % 50 == 0 || i == ids.length - 1
+    print "\rfetched metadata: #{i + 1}/#{ids.length}"
+  end
+end
+puts
+
+# 3. Aggregate.
+by_sender = Hash.new { |h, k| h[k] = { count: 0, unread: 0, trashed: 0, newsletters: 0,
+                                       in_inbox: 0, promo: 0, update: 0, social: 0,
+                                       last_ts: 0, sample_subjects: [] } }
+records.each do |r|
+  key = r[:email] || '(unknown)'
+  s = by_sender[key]
+  s[:count]    += 1
+  s[:unread]   += 1 if r[:is_unread]
+  s[:trashed]  += 1 if r[:in_trash]
+  s[:newsletters] += 1 if r[:has_list]
+  s[:in_inbox] += 1 if r[:in_inbox]
+  s[:promo]    += 1 if r[:is_promo]
+  s[:update]   += 1 if r[:is_update]
+  s[:social]   += 1 if r[:is_social]
+  s[:last_ts]   = [s[:last_ts], r[:ts_ms]].max
+  s[:sample_subjects] << r[:subject] if s[:sample_subjects].length < 3 && r[:subject]
+end
+
+# 4. Write everything to JSON for further analysis.
+File.write(options[:out], JSON.pretty_generate({
+  query:   options[:query],
+  limit:   options[:limit],
+  fetched: records.length,
+  records: records,
+  by_sender: by_sender.transform_values { |v| v.merge(last_iso: v[:last_ts].positive? ? Time.at(v[:last_ts] / 1000).utc.iso8601 : nil) }
+}))
+
+# 5. Print top-line stats.
+total = records.length
+puts
+puts "=== Summary (n = #{total}) ==="
+puts "  unread:           #{records.count { |r| r[:is_unread] }}"
+puts "  in inbox:         #{records.count { |r| r[:in_inbox] }}"
+puts "  in trash:         #{records.count { |r| r[:in_trash] }}"
+puts "  newsletters:      #{records.count { |r| r[:has_list] }}"
+puts "  promo cat:        #{records.count { |r| r[:is_promo] }}"
+puts "  updates cat:      #{records.count { |r| r[:is_update] }}"
+puts
+puts "=== Top 25 senders by volume ==="
+printf "%6s  %6s  %6s  %6s  %s\n", 'count', 'unread', 'trash', 'newsl', 'sender'
+by_sender.sort_by { |_, v| -v[:count] }.first(25).each do |email, s|
+  printf "%6d  %6d  %6d  %6d  %s\n",
+    s[:count], s[:unread], s[:trashed], s[:newsletters], email
+end
+puts
+puts "Wrote #{options[:out]}"

data/bin/gmcp

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+# Bundler only in a checkout; an installed gem resolves through RubyGems.
+require 'bundler/setup' if File.exist?(File.expand_path('../Gemfile', __dir__))
+require_relative '../lib/gmcp'
+
+accounts = if ENV['GMCP_ACCOUNTS']
+  ENV['GMCP_ACCOUNTS'].split(',').map(&:strip).reject(&:empty?)
+elsif ENV['GMCP_ACCOUNT']
+  [ENV['GMCP_ACCOUNT']]
+else
+  abort 'Set GMCP_ACCOUNTS (comma-separated) or GMCP_ACCOUNT to the Google account(s) to use'
+end
+
+# stderr, not stdout — stdout is the MCP stdio transport. This is the one place
+# an operator can see what a given process was actually granted.
+warn "GMCP: accounts     = #{accounts.join(', ')}"
+warn "GMCP: capabilities = #{GMCP::Capabilities.summary}"
+
+# Some connectors resolve their principal outside GMCP, so the account list
+# above does not bound them. Say so rather than letting it imply containment.
+unscoped = GMCP::Capabilities.unscoped_grants
+unless unscoped.empty?
+  by_connector = unscoped.group_by { |cap| GMCP::Capabilities.connector_for(cap).fetch('name') }
+  by_connector.each do |connector, caps|
+    verb = caps.one? ? 'reaches' : 'reach'
+    warn "GMCP: NOTE — #{caps.join(', ')} #{verb} the #{connector} principal, which " \
+         'GMCP_ACCOUNTS does NOT narrow.'
+  end
+  warn 'GMCP: NOTE — call voice_account to see which account that currently is.' if by_connector.key?('voice')
+end
+
+GMCP::Server.run!(accounts: accounts)

data/bin/gmcp-auth

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+
+# Authorize a Google account for GMCP from the command line.
+#
+#   bin/gmcp-auth <account>
+#
+# Opens the OAuth consent page in a browser and captures the redirect on a
+# local callback server. Use this when the gmcp_authorize MCP tool isn't
+# reachable (server down, tools not loaded in the current session).
+#
+# Google shut off the out-of-band (urn:ietf:wg:oauth:2.0:oob) flow in 2022, so
+# there is no copy-the-code path any more — the loopback redirect is the only
+# option for a desktop client, and it is what Auth.authorize_interactive!
+# implements.
+
+# Bundler only in a checkout; an installed gem resolves through RubyGems.
+require 'bundler/setup' if File.exist?(File.expand_path('../Gemfile', __dir__))
+require_relative '../lib/gmcp'
+
+# Unbuffered so progress is visible when stdout is a pipe, not just a TTY.
+$stdout.sync = true
+
+# Generous by default: this waits on a human completing a browser consent
+# screen, not on a machine. Override with GMCP_AUTH_TIMEOUT (seconds).
+TIMEOUT = Integer(ENV.fetch('GMCP_AUTH_TIMEOUT', 900))
+
+account = ARGV[0]
+if account.nil? || account.empty?
+  abort "Usage: #{File.basename($PROGRAM_NAME)} <account>\n" \
+        "  e.g. #{File.basename($PROGRAM_NAME)} you@example.com"
+end
+
+unless File.exist?(GMCP::Auth.credentials_path)
+  abort "credentials.json not found at #{GMCP::Auth.credentials_path}\n\n" \
+        "1. https://console.cloud.google.com/ → APIs & Services → Credentials\n" \
+        "2. Create an OAuth 2.0 Client ID (Desktop app)\n" \
+        "3. Save the JSON to that path"
+end
+
+result = Queue.new
+url = GMCP::Auth.authorize_interactive!(
+  account: account,
+  timeout: TIMEOUT,
+  on_success: ->(_acct) { result << :authorized },
+  on_failure: ->(_acct, error) { result << error }
+)
+
+puts "Authorizing #{account} — a browser window should have opened."
+puts
+puts "If it did not, open this manually:"
+puts "  #{url}"
+puts
+puts 'Waiting for the callback…'
+
+case (outcome = result.pop(timeout: TIMEOUT))
+when nil       then abort "Timed out after #{TIMEOUT}s with no callback. Nothing was stored."
+when Exception then abort "Authorization failed: #{outcome.class}: #{outcome.message}"
+end
+
+# Prove the stored token actually works rather than trusting the callback.
+begin
+  GMCP::Auth.access_token(account: account)
+rescue StandardError => e
+  abort "Callback completed but the stored token does not work: #{e.class}: #{e.message}"
+end
+
+puts "Authorized #{account}."
+puts "Token stored at #{GMCP::Auth.token_path(account)}"