ZeroHrs MCP server

This public local MCP server exposes the signed-in user's ZeroHrs data to Codex. It uses the ZeroHrs API and its user authorization checks.

For a shareable, agent-oriented installation guide, see INSTALL.md.

Install in Codex

Requires Node.js 20 or newer. Inspect any existing zerohrs entry before replacing it, then install the public tagged release:

codex mcp add zerohrs -- npx -y github:ZeroHrs-Org/zerohrs-mcp#v0.2.0

Set default_tools_approval_mode = "writes" for this server in ~/.codex/config.toml, restart Codex, and call the login tool with no arguments.

Tools

Read-only tools:

• search_zero
• list_meetings
• list_transcripts
• search_transcripts
• get_transcript
• list_tasks
• get_task
• get_meeting_prep

Write tools, which Codex asks to approve:

• login
• disconnect
• create_task
• update_task
• add_meeting_prep_note

The server intentionally has no tools for sending email or messages, scheduling meeting bots, sharing transcripts, deleting data, or performing actions in external services.

get_transcript returns the transcript summary by default. It can include linked tasks and query-matched speaker blocks, but it never loads every transcript turn by default.

Login and disconnect

The server runs locally over STDIO. It does not require a session token at startup.

Call login with no arguments. It returns a clickable, short-lived URL on:

• http://localhost:3100

Open the URL and select Sign in with Google. The official Google sign-in opens in your system browser, outside the Codex embedded browser. The local MCP exchanges the Google credential with ZeroHrs and validates the returned session through /auth/profile. No Google credential or ZeroHrs session token passes through Codex chat. The URL expires after ten minutes and stops listening after success, expiration, or disconnect.

Browser login includes the public ZeroHrs production Google client ID. Administrators can override it with ZEROHRS_GOOGLE_WEB_CLIENT_ID or GOOGLE_WEB_CLIENT_ID. For repository development, it can also read GOOGLE_WEB_CLIENT_ID from backend/control-plane/.env. The Google web client must authorize http://localhost:3100 as a JavaScript origin. Set ZEROHRS_MCP_LOGIN_PORT only when that alternate localhost origin is also authorized.

The API destination is not accepted from the tool call. It defaults to https://control-plane.zerohrs.com and can be set by the administrator through ZEROHRS_API_BASE_URL before Codex starts, for example when using a local or staging control plane.

After browser sign-in, only the validated ZeroHrs token is saved at ~/.zerohrs/codex-mcp-session.json with 0600 permissions. The saved session becomes active immediately without restarting Codex.

Call disconnect to cancel any pending browser login and remove that local credential file. It does not call /auth/logout, revoke the token, or sign out any other ZeroHrs app session. Calling it again is safe.

Do not add a session token to .codex/config.toml, a committed .env file, chat, or shell history. The saved token is sent only as Authorization: Bearer <token> to the administrator-configured ZeroHrs API URL. The control plane remains responsible for user access checks on meetings, transcripts, tasks, contacts, prep notes, and briefs.

Restart Codex after initially adding or updating this MCP server, then use /mcp to confirm the zerohrs server and its tools are available.

Release contents

This repository contains the standalone public distribution. The executable bundle is dist/index.mjs; its runtime dependencies remain normal npm packages.