Google Workspace MCP

Google integration is optional. It has two parts, which share your Google Cloud client:

• Email answers on a call (the check_email plugin). A read-only Gmail sign-in lets the voice model answer "anything from the bank today?" itself, in about five seconds, rather than starting a task.
• Gmail and Calendar for the agents (GOOGLE_WORKSPACE_MCP). Claude doesn't need this, because the Claude CLI carries your authorized claude.ai connectors (Gmail, Calendar, Drive…), and every Claude task inherits them. Codex has no connectors. If you use Codex, its tasks have no mailbox or calendar until you turn this on. It gives every task a workspace-mcp server that can send mail and manage your calendar.

In keryx setup, the Google section connects the agents, and the email part is the check_email plugin in the Plugins section. The commands on this page set up each part on its own.

The Google Cloud client

1. Create the client with the Google setup guide, which keryx setup also links to.
2. Publish the app "In production". Otherwise, the sign-in stops working after seven days.
3. Pass the downloaded JSON to the first sign-in with --client-file. Keryx copies it to KERYX_HOME/google_client_secret.json, readable only by you, and uses that copy from then on.

Email answers: keryx auth login gmail

The Gmail sign-in takes two steps, because the machine Keryx runs on usually has no browser:

1. Start the sign-in, and open the link it prints on any device:

   uv run keryx auth login gmail --client-file ~/Downloads/client_secret_….json

2. Approve the access. The browser then lands on an http://localhost:1/?… address that doesn't load. Copy that address, and pass it to the second step:

   uv run keryx auth login gmail --callback-url 'http://localhost:1/?…'

The refresh token goes to DATA_DIR/gmail_token.json. The sign-in alone doesn't offer anything on a call. Turn the plugin on as well:

uv run keryx plugins install check_email

check_email summarizes with the claude CLI. So it needs the Claude extra installed (uv sync --extra claude), even when Codex does your tasks. The model that answers, and how hard it thinks, are model and effort in DATA_DIR/tools/check_email.toml. A change there takes effect from the next call. keryx plugins and keryx doctor say whether the plugin is on, or why it's refused.

Agents: keryx auth login google-workspace

uv run keryx auth login google-workspace

This turns GOOGLE_WORKSPACE_MCP on, and starts workspace-mcp once by hand. It calls a harmless tool, so that Google's consent screen appears now, while you're there, rather than in the middle of a task. It prints a link to approve.

The consent page listens on localhost:8000. If the machine has no browser, first run ssh -L 8000:localhost:8000 <that host> from the machine you're at.

The credentials are stored under DATA_DIR/google/, and every task reuses them. Set USER_GOOGLE_EMAIL to the account the tasks act as; keryx setup asks for it.

If Google tools start failing inside a task, the stored credentials have most likely expired. Run keryx auth login google-workspace again. keryx auth status shows every sign-in, and whether it's done.