Skip to content

Connect Codex to Hourbun

By Fred Wu, maker of Hourbun · Checked · Report a mistake

The short answer

Codex reads the token of an MCP server from an environment variable. Export a token of the page API & MCP as HOURBUN_TOKEN, then run codex mcp add hourbun with the address of the server and --bearer-token-env-var HOURBUN_TOKEN. Keep the export line in your shell profile, so that each new terminal has the token, and Codex tracks time and reads your projects as you.

Set it up

The setup that the page API & MCP of Hourbun gives, with the address of the server. In a setup with a token, put the text of your token in the place of YOUR_TOKEN.

Codex Token Docs of Codex Run it in a terminal, and keep the export line in your shell profile: Codex reads the token from HOURBUN_TOKEN.
export HOURBUN_TOKEN="YOUR_TOKEN"
codex mcp add hourbun --url https://hourbun.com/api/v1/mcp --bearer-token-env-var HOURBUN_TOKEN

What to ask

Ask in your own words: the assistant chooses the tools of Hourbun. Under each question, the tools that it calls. The tools of invoices and uninvoiced time answer for the owner and the admins.

  • “Who am I in Hourbun, and which workspace is this?”

    Calls whoami

  • “Change yesterday's 2 hours on Website to 2.5.”

    Calls list_time_entries then update_time_entry

  • “How many hours of Website are not invoiced yet?”

    Calls get_uninvoiced

  • “Track 3 hours on Website for today: API work.”

    Calls list_projects then create_time_entry

The token in an environment variable#

Codex keeps the name of the variable in its setup, not the token: codex mcp add hourbun --url … --bearer-token-env-var HOURBUN_TOKEN adds the server, and Codex reads HOURBUN_TOKEN when it connects. The setup exports HOURBUN_TOKEN first, so the command works in the same terminal.

Keep the export line in your shell profile, such as ~/.zshrc or ~/.bashrc, so that each new terminal has the token. Without it, Codex reaches Hourbun with no token, and Hourbun refuses each request. A profile is a file of your own: keep it out of a repository that others read.

When the token expires or you revoke it, make a new token and change the export line: the setup of Codex stays as it is.

Make a token#

On the page API & MCP of Hourbun, New token opens a form with the Name, the Access and Expires after. Name the token after Codex, so that the list says where it is used. Read lets Codex read your projects, clients, time and expenses; Read and write also lets it track time and use your timer. A token can end after 7, 30, 90 or 365 days, or never.

Create token shows the text of the token once, with Copy token. Under Use it with an AI assistant, choose Codex: its setup has the token in it, and Copy setup copies it whole. After Done, no page shows the token again: Hourbun keeps only a secure hash of it. The token acts as you, in this workspace and with your role, until it expires or you revoke it.

What Codex can do#

Hourbun has one MCP tool for each operation of its API, and Codex gets only the tools that your role and the access allow. With Read, it reads your projects, clients, tasks, time entries, timer and expenses. With Read and write, it also tracks time, changes and deletes your time entries, and starts, pauses, resumes, stops and discards your timer. Invoices and uninvoiced time are for the owner and the admins of the workspace: a member or a manager gets no tool for them.

Each tool calls what the REST API calls, so Codex gets the same answers, amounts and refusals as a script. An entry on an issued invoice, or an approved or submitted one, is locked, and a money field that your role does not see is left out. Hourbun keeps no prompt and no chat: a tool receives only its arguments.

Stop the connection#

Each token and each connection is in the list of the page API & MCP, with its access, its status and the day of its last use. Revoke ends it at once, and Hourbun refuses the next request of Codex. The owner and the admins of the workspace can revoke it too, and it stops when you leave the workspace.

Questions

Questions and answers

Where does Codex keep my Hourbun token?

In the environment variable HOURBUN_TOKEN of your shell, not in the setup of Codex. Keep the export line in your shell profile, and change it when you make a new token.

Can I give Codex a token that only reads?

Yes. Choose Read for the token: Codex then gets only the tools that read, and changes no time and no timer. Read and write also lets it track time and use your timer.

What happens when my Hourbun token expires?

Hourbun refuses each request of Codex with the token. Make a new token on the page API & MCP, and change the export line of HOURBUN_TOKEN.

Sources

The setup of Codex follows its own documents, read on 13 November 2026:

Try Hourbun for free.

14 days, no card. Add a client, track your first hour, and send the invoice.