Knowledge Hub

The HQ Knowledge Hub

Plain-English guides to HQ, from your first install to rolling it out across your whole team.

On this page

Daily Use

Connecting Gmail and Google Drive to HQ

6 min read Updated Nov 2026

Google Workspace users who want HQ to read their Gmail or Google Drive.

Once it's connected, you can ask HQ about your email and files in plain words, like "list my Gmail labels" or "find the email from Sam about the launch."

Why do Gmail and Drive say "Coming soon" in HQ? HQ's own Google app is still in Google's verification review. Until Google approves it, this page is the do-it-yourself way to connect them.

Google Calendar doesn't need any of this. It already connects through HQ's built-in Google option. In the HQ console, open your personal Integrations page, click Add integration, choose Google Integrations, and pick Calendar.

Already connected Gmail in Claude? That connection belongs to Claude, and HQ can't use it. Connect Gmail inside HQ with the steps below.

Before you start#

Read this first. It decides whether you can finish today.

  • You need a Google Workspace account. A personal @gmail.com account won't work.
  • Google has to approve your project first. HQ connects to Gmail and Drive through Google's AI connections, which are still in preview. Google only turns them on for projects in its Workspace Developer Preview Program. Approval usually takes a couple of days.
  • You need HQ on your Mac, signed in. To check, open the Terminal app and run hq whoami.

You'll work in two places: the Google Cloud console in your browser, and the Terminal app on your Mac. Don't use the terminal button inside Google Cloud (the >_ icon). That's Google's terminal, and HQ isn't installed there.

Step 1: Create a Google Cloud project#

  1. Go to console.cloud.google.com and sign in with your Workspace account.
  2. Click the project picker at the top of the page, then New project.
  3. Name it (for example "HQ connection") and click Create.
  4. Make sure the new project is selected in the project picker.

Step 2: Apply to Google's preview program#

  1. Go to developers.google.com/workspace/preview.
  2. Read the terms and fill in the form. It asks for your Workspace account and the project from Step 1.
  3. Google emails you an invite to a Google Group. Accept it.
  4. Wait for Google's email confirming your project is registered.

If you haven't heard back in a week, email workspace-dpp-mod@google.com.

You can do Steps 3 to 5 while you wait. The connection won't read anything until Google approves you.

Good to know: Google may use data sent through preview features, and they come "as is." You can only use them inside your own company. Connecting your own Gmail and Drive to HQ is fine.

Step 3: Turn on the Google APIs#

  1. In Google Cloud, open the menu and go to APIs & Services, then Library.
  2. Search for each one you want and click Enable:
  • Gmail: Gmail API and Gmail MCP API
  • Drive: Google Drive API and Drive MCP API

The Drive names may look slightly different in the Library.

Step 4: Set up the sign-in screen#

  1. Go to APIs & Services, then OAuth consent screen. Google may send you to Google Auth Platform instead. That's the same place.
  2. Enter an app name (for example "HQ") and your email address for the support and contact fields.
  3. For Audience, pick Internal if only people in your company will use it. Otherwise pick External.
  4. If you picked External, open Audience in the left menu and add your own email under Test users. Without this, Google blocks your sign-in.
  5. Click Save.

Step 5: Create the sign-in client#

  1. In Google Auth Platform, click Clients in the left menu, then + Create client.
  2. For Application type, pick Web application. A desktop app client won't work.
  3. If Google shows Use this client for an AI-powered agent, tick it.
  4. Under Authorized redirect URIs, click + Add URI and paste exactly:
Redirect URI
   https://hq.computer/api/integrations/mcp-oauth/callback
  1. Click Create.

A box opens with a Client ID and a Client secret. Leave it open for the next step.

The Client secret is private, like a password. Don't paste it into a chat, an email, or a Terminal line by itself. The next step handles it safely.

Step 6: Connect Gmail in HQ#

You'll copy two things, one at a time, and run a command after each. Open the Terminal app on your Mac (press Cmd+Space and type "Terminal").

  1. In the Google box, click the copy icon next to Client ID. Then run this in Terminal. It prints nothing, which is normal.
bash
   pbpaste > /tmp/hq-google-client-id.txt
  1. In the Google box, click the copy icon next to Client secret. Then run this in the same Terminal window, with your-company changed to your HQ company name:
bash
   pbpaste | hq integrations connect --mcp-url 'https://gmailmcp.googleapis.com/mcp/v1' --company your-company --provider gmail --client-id "$(tr -d '[:space:]' < /tmp/hq-google-client-id.txt)" --client-secret-stdin --personal

This reads the secret straight from your clipboard, so it never shows on screen or lands in your Terminal history.

  1. Your browser opens a Google sign-in page. If it doesn't, open the link Terminal prints. Approve access. If Google says the app isn't verified, click Continue. That's expected for an app you made yourself.
  2. When it's done, your browser opens the HQ console.
  3. Clean up:
bash
   rm /tmp/hq-google-client-id.txt

Then copy any other text so the secret is no longer on your clipboard.

Step 7: Check that it works#

Run:

bash
hq integrations list --company your-company --usable

You should see Googleapis (gmailmcp.googleapis.com) in the list.

Then ask HQ: "List my Gmail labels." If it lists them, you're connected.

Connecting Google Drive#

Follow Step 6 again with the same Client ID and secret. In the second command, change only the address after --mcp-url and the name after --provider:

App--mcp-url--provider
Gmailhttps://gmailmcp.googleapis.com/mcp/v1gmail
Drivehttps://drivemcp.googleapis.com/mcp/v1drive

Make sure you turned on both Drive APIs in Step 3.

If something goes wrong#

What you seeWhat to do
zsh: command not found: hqYou're probably in Google's terminal. Use the Terminal app on your Mac. If it still fails, type /usr/local/bin/hq instead of hq.
zsh: no such file or directoryPart of the command, like <CLIENT_ID>, wasn't replaced. Use the commands in Step 6, which only need your company name.
Google says Error 401: invalid_clientThe Client ID is wrong or missing, or the client is brand new. Redo Step 6, or wait 5 minutes and try again.
Google says redirect_uri_mismatchThe client isn't a Web application, or the redirect URI doesn't match exactly. Check Step 5.
Google says Access blockedYour email isn't a test user. Add it under Audience, then Test users (Step 4).
HQ says Gmail MCP API has not been used in projectThe API isn't turned on. Enable it (Step 3), wait a few minutes, and try again.
Google or HQ says The caller does not have permissionEither Google hasn't approved your project yet (Step 2), or one of the APIs isn't turned on (Step 3). Check both, wait a few minutes, and try again.
HQ says the project must be enrolled in the Google Workspace Developer Preview ProgramGoogle hasn't approved your project yet. Finish Step 2 and wait for Google's email.

Disconnecting#

To disconnect Gmail or Drive from HQ, find its provider name with hq integrations list --company your-company, then run:

bash
hq integrations disconnect --company your-company --provider <provider-name>

To turn it off on Google's side too, delete the client in Google Cloud under Google Auth Platform, then Clients.

If you get stuck#

See The "I'm Stuck" Guide, or email support@hqforwork.com. More on connecting apps in Connecting Your Apps to HQ.