[Integrations](https://hourbun.com/integrations)

# [Connect Cursor to Hourbun](https://hourbun.com/integrations/cursor)

By Fred Wu, maker of Hourbun · Checked 13 November 2026 · [Report a mistake](mailto:support@hourbun.com)

## The short answer

Cursor reads its MCP servers from mcp.json: put the setup of Hourbun in ~/.cursor/mcp.json for every project, or in .cursor/mcp.json of one project. With the header and a token of the page API & MCP, it connects at once; without the headers, Cursor signs in to Hourbun with OAuth instead. It then tracks time, runs your timer and reads your projects as you.

## Where in the app

- API & MCP → New token
- API & MCP → Connect an AI assistant

## What you need

- A Hourbun account in an active workspace
- Cursor
- A token of the page API & MCP, or a sign-in to Hourbun with OAuth

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

### Cursor (Token)

Put it in ~/.cursor/mcp.json, or in .cursor/mcp.json of a project. Without the headers, Cursor signs in to Hourbun with OAuth instead.

[Docs of Cursor](https://cursor.com/docs/context/mcp)

```
{
  "mcpServers": {
    "hourbun": {
      "url": "https://hourbun.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_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.

- “Track 45 minutes on Website for the review of this pull request.” Calls `list_projects`, then `create_time_entry`.
- “Which tasks does the Website project have?” Calls `list_projects`, then `get_project`.
- “Pause my timer.” Calls `pause_timer`.
- “What did I track this week?” Calls `whoami`, then `list_time_entries`.

## For you, or for one project

`~/.cursor/mcp.json` adds Hourbun to every project that you open in Cursor; `.cursor/mcp.json` in a project adds it to that project only. The server is `hourbun` under `mcpServers`, with the address and the header `Authorization`.

A project file with a token in it holds a secret. Keep it out of a repository that others read, or leave the headers out and sign in.

## Sign in instead of a token

Without the headers, Cursor signs in to Hourbun with OAuth. Hourbun sends its answer to the address that the Cursor app registered on your device, and the page that asks you to allow it names the app on this device. Each teammate then connects with their own account and role, and no token is in a file.

## 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 Cursor, so that the list says where it is used. **Read** lets Cursor 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 Cursor: 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.

## Allow the connection

When Cursor opens Hourbun, sign in, and Hourbun asks you to allow it. The page names Cursor and where Hourbun sends your answer. Choose the **Workspace** and the **Access**: **Read**, or **Read and write** to also track time and use your timer. Then press **Allow**, or **Deny**.

The connection works in that one workspace, with your role there. Hourbun keeps it as a token of yours, with an access token that lives 1 hour and a refresh token that ends after 90 days without use, both only as secure hashes. The access of a connection never changes: for other access, connect Cursor again.

## What Cursor can do

Hourbun has one MCP tool for each operation of its API, and Cursor 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 Cursor 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 Cursor. The owner and the admins of the workspace can revoke it too, and it stops when you leave the workspace.

## Questions and answers

### Does Hourbun work with Cursor?

Yes. Cursor connects to Hourbun's MCP server from mcp.json, with a token in the header, or with a sign-in to Hourbun when the headers are left out.

### Should I put the Hourbun setup in my project's .cursor/mcp.json?

Only without a token, or in a repository that nobody else reads. ~/.cursor/mcp.json keeps the token in your own folder, and a sign-in keeps every token out of a file.

### Can Cursor see the invoices of my workspace?

Only when your role is admin or owner: a member or a manager gets no tool for invoices or uninvoiced time. A token or a connection with Read reads and changes nothing.

## Sources

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

- [Cursor documentation](https://cursor.com/docs/context/mcp)

## Related

- [The MCP server in the API reference](https://hourbun.com/developers#mcp)
- [Time tracking in the help centre](https://hourbun.com/help/time-tracking)
- [Time tracking apps with an MCP server](https://hourbun.com/best/time-tracking-apps-with-an-mcp-server)
- [ChatGPT](https://hourbun.com/integrations/chatgpt)
- [Claude](https://hourbun.com/integrations/claude)
- [Claude Code](https://hourbun.com/integrations/claude-code)
- [Codex](https://hourbun.com/integrations/codex)
- [VS Code](https://hourbun.com/integrations/vscode)
- [Gemini CLI](https://hourbun.com/integrations/gemini-cli)
- [All integrations](https://hourbun.com/integrations)
