# ZeroHrs MCP server

This public local MCP server gives Codex access to the signed-in user's Zero data through the same user-scoped API paths used by Zero's OpenClaw agent.

For a shareable, agent-oriented installation guide, see [`INSTALL.md`](./INSTALL.md).

## Install in Codex

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

```sh
codex mcp add zerohrs -- npx -y github:ZeroHrs-Org/zerohrs-mcp#v0.3.0
```

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

## OpenClaw-compatible tools

The MCP includes these names from Zero's OpenClaw agent:

- `search_zero`
- `search_contacts`
- `add_contact`
- `get_meetings`
- `get_transcripts`
- `get_meeting_transcript_by_id`
- `get_user_owned_tasks`
- `create_user_owned_task`
- `insert_prep_notes_for_meeting`
- `replace_generated_prep_notes_for_meeting`
- `schedule_meeting_bot`
- `get_morning_brief_by_date`

It also keeps these focused MCP convenience tools:

- `list_meetings`
- `list_transcripts`
- `search_transcripts`
- `get_transcript`
- `list_tasks`
- `get_task`
- `get_meeting_prep`
- `create_task`
- `update_task`
- `add_meeting_prep_note`

The remaining tools are `login` and `disconnect`, for a total of 24.

Codex asks for approval before writes and external actions. `schedule_meeting_bot` is an external action and should only run after an explicit user request. `add_contact` may update an existing contact with the same email, `update_task` overwrites selected task fields, and generated-prep replacement removes the prior generated notes before saving the replacement. The server intentionally excludes email, messaging, transcript sharing, direct record-deletion tools, onboarding, runtime control, and administrator tools. The internal generated-morning-brief replacement tool is also excluded because its claim-token workflow is not a public user action.

`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.

## Hosted login

The MCP runs locally over STDIO and does not require a token or Google client configuration at startup.

Call `login` with no arguments. It returns a short-lived loopback URL on `http://127.0.0.1:3100`. The local page opens the hosted sign-in at `https://app.meetzero.ai/mcp/login` in the system browser.

The hosted page signs the user in with Zero's Google client, creates a single-use authorization code, and returns only that code and the original state to the loopback callback. The local MCP exchanges the code with its private PKCE verifier, validates the returned MCP-scoped session through `/auth/profile`, and saves it locally. Google credentials and Zero session tokens never pass through Codex chat or browser callback URLs.

Public users do not need `GOOGLE_WEB_CLIENT_ID`, a repository checkout, or any ZeroHrs environment file.

For local or staging development only:

- `ZEROHRS_MCP_LOGIN_URL` overrides the hosted sign-in page. Remote values must use HTTPS. HTTP is accepted only for loopback hosts.
- `ZEROHRS_MCP_LOGIN_PORT` changes the local callback port.
- `ZEROHRS_API_BASE_URL` changes the control-plane destination before Codex starts.

After sign-in, only the validated MCP-scoped token is saved at `~/.zerohrs/codex-mcp-session.json` with `0600` permissions. Call `disconnect` to cancel a pending login and remove that local credential. It does not revoke the token or sign out other Zero sessions.

Do not add a session token to `.codex/config.toml`, a committed `.env` file, chat, or shell history.

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

## Development

```sh
pnpm --filter @zerohrs/mcp build
pnpm --filter @zerohrs/mcp test
pnpm --filter @zerohrs/mcp typecheck
```