Hourbun
Time tracking and invoicing for freelancers and small teams: start and stop timers, add time entries, and read projects, expenses and uninvoiced time from your AI assistant.
Servidor MCP alojado
npx add-mcp 'https://hourbun.com/api/v1/mcp'Se instala en Claude Code, Codex, Cursor y más
Documentación
Authentication
Each request has a personal token of a member of a workspace in its Authorization header. A member makes a token on the API page of the app, and sees its text only once. The token acts as that member, in that workspace, with the role of the member: the API never shows more than the app shows the member.
A token with Read access can only read. A token with Read and write access can also track time and drive the timer. A revoked or expired token, and the token of an archived member, get 401.
curl https://hourbun.com/api/v1/me \
-H "Authorization: Bearer YOUR_TOKEN"
A money field that the role does not see is left out of each result: GET /me says which money the role shows. A member and a manager see no rates, amounts or costs of time entries.
Conventions
- JSON with snake_case keys, and UUIDs as ids.
- A date is an ISO date in the time zone of the workspace; a time is ISO 8601 in UTC.
- Hours are a decimal string ("1.50"). Money is a decimal string beside its currency ("200.00", "AUD").
- A list of entries, expenses or invoices has data, page, per_page and next_page (null on the last page): page from 1, per_page up to 100.
- A range is from and to, both ISO dates, at most 366 days, both dates included. For "this month", give the first and the last day of the month.
- A record that the token does not see is 404.
curl -X POST https://hourbun.com/api/v1/time_entries \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"project_task_id": "…", "hours": "2h", "notes": "Design review"}'
Endpoints
Each endpoint is also an MCP tool of the same name and the same rules. The OpenAPI document has the full schema of each answer.
The token
GET /api/v1/me
The token, its member and its workspace
The workspace, the member and the role of the token, its access, and which money the role shows.
MCP tool whoami
Projects
GET /api/v1/projects
The projects, with the project tasks that take time
Each project has its client and tasks: the project tasks that take new time, whose project_task_id a new entry or timer names. For an admin and the owner, the projects of the workspace; for another role, the projects that take its time, with ids and names only.
MCP tool list_projects
status query · active | archived | all
For an admin and the owner; another role reads the active records that take its time
GET /api/v1/projects/{id}
A project
MCP tool get_project
id path · uuid · required
The id of the project
Clients
GET /api/v1/clients
The clients
For an admin and the owner, the clients of the workspace; for another role, the clients of the projects that take its time, with ids and names only. By name.
MCP tool list_clients
status query · active | archived | all
For an admin and the owner; another role reads the active records that take its time
GET /api/v1/clients/{id}
A client
MCP tool get_client
id path · uuid · required
The id of the client
Tasks
GET /api/v1/tasks
The tasks
For an admin and the owner, the tasks of the workspace; for another role, the tasks of the projects that take its time, with ids and names only. By name.
MCP tool list_tasks
status query · active | archived | all
For an admin and the owner; another role reads the active records that take its time
GET /api/v1/tasks/{id}
A task
MCP tool get_task
id path · uuid · required
The id of the task
Time entries
GET /api/v1/time_entries
The time entries of a range of days
One page of the entries of every member whose time the token sees: the own time, and for a manager the time of a teammate on the projects that the manager manages, for an admin and the owner all time. By date, then creation.
MCP tool list_time_entries
from query · date · required
The first day
to query · date · required
The last day: the range is at most 366 days, both dates included
project_id query · uuid
Only this project
member_id query · uuid
Only this member
page query · integer
From 1
per_page query · integer, 1–100
50 by default
POST /api/v1/time_entries
Track time
A new entry of a project_task_id of GET /api/v1/projects, on spent_on (today of the workspace by default). The rate, the currency and the billable flag come from the project.
MCP tool create_time_entry Needs a token with Read and write
hours body · string or number · required
A duration: 2h, 1:30, 90m, 1.5, or a number of hours
project_task_id body · uuid · required
A project_task_id of a project of GET /api/v1/projects
member_id body · uuid
A teammate whose time the token may change; the member of the token by default
notes body · string
project_id body · uuid
The project of the task, when the client chose it: a project task of another project is other_project
spent_on body · date
Today of the workspace by default
GET /api/v1/time_entries/{id}
A time entry
MCP tool get_time_entry
id path · uuid · required
The id of the entry
PATCH /api/v1/time_entries/{id}
Change a time entry
MCP tool update_time_entry Needs a token with Read and write
id path · uuid · required
The id of the entry
hours body · string or number
notes body · string
project_id body · uuid
The project of the task, when the client chose it: a project task of another project is other_project
project_task_id body · uuid
spent_on body · date
DELETE /api/v1/time_entries/{id}
Delete a time entry
MCP tool delete_time_entry Needs a token with Read and write
id path · uuid · required
The id of the entry
Timer
GET /api/v1/timer
The timer
MCP tool get_timer
POST /api/v1/timer/discard
Discard the timer and its time
MCP tool discard_timer Needs a token with Read and write
timer_id body · uuid
The timer that the client saw; the timer of now by default
POST /api/v1/timer/pause
Pause the timer
Also in a paused workspace.
MCP tool pause_timer Needs a token with Read and write
timer_id body · uuid
The timer that the client saw; the timer of now by default
POST /api/v1/timer/resume
Resume the timer
MCP tool resume_timer Needs a token with Read and write
timer_id body · uuid
The timer that the client saw; the timer of now by default
POST /api/v1/timer/start
Start the timer
A new timer of a project_task_id of GET /api/v1/projects, on today of the workspace.
MCP tool start_timer Needs a token with Read and write
project_task_id body · uuid · required
notes body · string
project_id body · uuid
The project of the task, when the client chose it: a project task of another project is other_project
POST /api/v1/timer/stop
Stop the timer
The entry of the timer, in time_entry. Also in a paused workspace.
MCP tool stop_timer Needs a token with Read and write
timer_id body · uuid
The timer that the client saw; the timer of now by default
Expenses
GET /api/v1/expenses
The expenses of a range of days
One page of the expenses of every member whose expenses the token sees, by the view of the time entries. By date, then creation.
MCP tool list_expenses
from query · date · required
The first day
to query · date · required
The last day: the range is at most 366 days, both dates included
project_id query · uuid
Only this project
member_id query · uuid
Only this member
page query · integer
From 1
per_page query · integer, 1–100
50 by default
GET /api/v1/expenses/{id}
An expense
MCP tool get_expense
id path · uuid · required
The id of the expense
Invoices
GET /api/v1/invoices
The invoices
One page of the invoices, newest first. A page after the last is empty.
MCP tool list_invoices Admins and the owner only
status query · all | draft | sent | overdue | paid | written_off | credit_notes
A tab of the invoice list; all by default leaves the credit notes out
page query · integer
From 1
per_page query · integer, 1–100
50 by default
GET /api/v1/invoices/{id}
An invoice, with its lines
MCP tool get_invoice Admins and the owner only
id path · uuid · required
The id of the invoice
Uninvoiced
GET /api/v1/uninvoiced
The uninvoiced time, fees and expenses
Without from and to, the Uninvoiced report of the app. With them (for "this month": the first and the last day of the month), only the time and the expenses of those days, and the fees left to invoice of the fixed-fee projects apart in fixed_fees, undated and out of the totals.
MCP tool get_uninvoiced Admins and the owner only
from query · date
The first day, with to
to query · date
The last day, with from
Errors and limits
Every refusal has one envelope, with the messages of each field in a 422. A client reads the code; the message is English.
{"error": {"code": "locked", "message": "The record is locked: …"}}
401
unauthorized The bearer token is missing, unknown, revoked or expired.
403
access_changed The access of the member of this token changed.
forbidden The role of the member of this token does not allow this.
plan_required This workspace is paused: it has no plan.
read_only_token This token can only read.
404
not_found Not found.
409
locked The record is locked: on an issued invoice, written off, billed elsewhere, approved or submitted.
on_draft The record is on a draft invoice: its project task cannot change.
timer_changed The timer changed: it is not the timer that this request names.
timer_running A timer runs already: stop it first.
timer_too_long The timer ran for longer than an entry can hold: discard it, or stop it in the app.
422
invalid The request has invalid fields.
other_project The project task is not a task of the project.
429
rate_limited Too many requests. Try again later.
A token makes at most 120 requests in 60 seconds, and an address at most 20 refused requests: the next one is a 429 with Retry-After in seconds.
MCP server
Hourbun is an MCP server, so an AI assistant can track time and answer "what is not invoiced this month?" as you. It has one tool for each endpoint, and a token sees only the tools that its role and its access allow.
An assistant that signs in with OAuth needs the address of the server alone: it opens Hourbun, where you sign in and allow it, in one workspace and with the access that you choose. Into another setup, paste a token in the place of YOUR_TOKEN:
Chat
ChatGPT
On chatgpt.com, open Plugins, select the plus button, then Add custom MCP server. Enter a name, paste this URL under Connection, choose OAuth, and confirm the warning. Select Create as a plugin, then sign in to Hourbun when ChatGPT asks. The policies of your account and workspace apply: an admin of a workspace may have to allow it.
https://hourbun.com/api/v1/mcp
Claude
On claude.ai or in the Claude desktop app, open Customize, Connectors, choose Add, then Add custom connector. Paste this URL and sign in to Hourbun when Claude asks: the connector then works in the Claude apps on your phone too. On a Team or Enterprise plan, an owner adds it in Organization settings, Connectors.
https://hourbun.com/api/v1/mcp
Perplexity
Open Settings, Connectors, choose Custom connector, then Remote. Paste this URL, choose OAuth, and sign in to Hourbun when Perplexity asks. It needs a Pro, Max or Enterprise plan.
https://hourbun.com/api/v1/mcp
Mistral Le Chat
Open Intelligence, Connectors, choose Add connector, then Custom MCP Connector. Paste this URL and sign in to Hourbun when Le Chat asks. An admin of the Mistral workspace adds it.
https://hourbun.com/api/v1/mcp
Desktop
Claude Desktop
With a token: put it in claude_desktop_config.json (Settings, Developer, Edit Config), then restart Claude. It runs the mcp-remote bridge with Node.js. To sign in to Hourbun instead, add the connector of Claude.
{
"mcpServers": {
"hourbun": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://hourbun.com/api/v1/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer YOUR_TOKEN"
}
}
}
}
Raycast
Run Install Server (Manage MCP Servers), choose the HTTP transport, paste this URL, keep the OAuth type Dynamic, and sign in to Hourbun when Raycast asks.
https://hourbun.com/api/v1/mcp
Warp
Add it in Settings, Agents, MCP servers: Add, Streamable HTTP or SSE Server (URL).
{
"hourbun": {
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
LM Studio
Put it in mcp.json (Program, Install, Edit mcp.json).
{
"mcpServers": {
"hourbun": {
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Terminal
Claude Code
Run it in a terminal. Claude Code can also sign in to Hourbun with OAuth: add the server without the header, then run /mcp in Claude Code.
claude mcp add --transport http hourbun https://hourbun.com/api/v1/mcp --header "Authorization: Bearer YOUR_TOKEN"
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
Gemini CLI
Run it in a terminal, in your project.
gemini mcp add --transport http --header "Authorization: Bearer YOUR_TOKEN" hourbun https://hourbun.com/api/v1/mcp
GitHub Copilot CLI
Run it in a terminal.
copilot mcp add --transport http --header "Authorization: Bearer YOUR_TOKEN" hourbun https://hourbun.com/api/v1/mcp
OpenCode
Put it in opencode.json of a project, or in ~/.config/opencode/opencode.json.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"hourbun": {
"type": "remote",
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
},
"oauth": false
}
}
}
Amp
Put it in ~/.config/amp/settings.json.
{
"amp.mcpServers": {
"hourbun": {
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Factory Droid
Run it in a terminal.
droid mcp add hourbun https://hourbun.com/api/v1/mcp --type http --header "Authorization: Bearer YOUR_TOKEN" --no-oauth
Qwen Code
Run it in a terminal.
qwen mcp add --transport http hourbun https://hourbun.com/api/v1/mcp --header "Authorization: Bearer YOUR_TOKEN"
Goose
Put it in ~/.config/goose/config.yaml, or add a Remote Extension (Streamable HTTP) with goose configure.
extensions:
hourbun:
name: hourbun
type: streamable_http
uri: https://hourbun.com/api/v1/mcp
headers:
Authorization: Bearer YOUR_TOKEN
enabled: true
timeout: 300
Grok Build
Run it in a terminal.
grok mcp add --transport http hourbun https://hourbun.com/api/v1/mcp --header "Authorization: Bearer YOUR_TOKEN"
Auggie
Run it in a terminal.
auggie mcp add hourbun --transport http --url https://hourbun.com/api/v1/mcp --header "Authorization:Bearer YOUR_TOKEN"
Pi
Run it in a terminal, and keep the export line in your shell profile: Pi reads the token from HOURBUN_TOKEN.
export HOURBUN_TOKEN="YOUR_TOKEN"
pi mcp add hourbun --url https://hourbun.com/api/v1/mcp --bearer-token-env-var HOURBUN_TOKEN
Editor
Cursor
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.
{
"mcpServers": {
"hourbun": {
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
VS Code
Put it in.vscode/mcp.json of a project. It needs GitHub Copilot. Without the headers, VS Code signs in to Hourbun with OAuth instead.
{
"servers": {
"hourbun": {
"type": "http",
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Antigravity
Put it in ~/.gemini/config/mcp_config.json (MCP Servers, Manage MCP Servers, View raw config).
{
"mcpServers": {
"hourbun": {
"serverUrl": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Cline
Put it in cline_mcp_settings.json (MCP Servers, Configure MCP Servers).
{
"mcpServers": {
"hourbun": {
"type": "streamableHttp",
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
},
"disabled": false
}
}
}
Kiro
Put it in ~/.kiro/settings/mcp.json, for the Kiro IDE and the Kiro CLI.
{
"mcpServers": {
"hourbun": {
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
TRAE
Put it in.trae/mcp.json of a project, or add it in Settings, MCP, Add Manually.
{
"mcpServers": {
"hourbun": {
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Zed
Put it in the settings.json of Zed, or add it in Settings, AI, MCP Servers.
{
"context_servers": {
"hourbun": {
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Roo Code
Put it in.roo/mcp.json of a project, or in the global mcp_settings.json.
{
"mcpServers": {
"hourbun": {
"type": "streamable-http",
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Kilo Code
Put it in kilo.jsonc of a project, or in ~/.config/kilo/kilo.jsonc.
{
"mcp": {
"hourbun": {
"type": "remote",
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
},
"oauth": false,
"enabled": true
}
}
}
Junie
Put it in ~/.junie/mcp/mcp.json, for Junie in JetBrains IDEs and in the terminal.
{
"mcpServers": {
"hourbun": {
"url": "https://hourbun.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Continue
Put it in ~/.continue/config.yaml.
mcpServers:
- name: hourbun
type: streamable-http
url: https://hourbun.com/api/v1/mcp
requestOptions:
headers:
Authorization: Bearer YOUR_TOKEN
Other
Microsoft Copilot Studio
In your agent, open Tools, Add a tool, New tool, then Model Context Protocol. Paste this URL as the server URL, choose OAuth 2.0 with Dynamic discovery, then create the connection and sign in to Hourbun.
https://hourbun.com/api/v1/mcp
Any MCP client
An assistant that connects to a remote MCP server over HTTP takes these two values. One that signs in with OAuth needs the URL alone.
URL https://hourbun.com/api/v1/mcp
Header Authorization: Bearer YOUR_TOKEN
Webhooks
The owner and the admins of a workspace add webhooks in Settings, API and webhooks: an https URL and its events. Hourbun posts each event as JSON, signed with the secret of the webhook.
Events
Invoices
invoice.issued Invoice issued
An invoice (not a credit note) leaves its draft: Issue, Send, or the issue of a recurring invoice. Data: the invoice with its lines.
invoice.paid Invoice paid
An invoice gets the status Paid: a manual payment, an online payment, or an applied deposit or payment. Data: the invoice with its lines.
Estimates
estimate.accepted Estimate accepted
The client accepts an estimate on its page. Data: the estimate with its totals and the answer.
estimate.declined Estimate declined
The client declines an estimate on its page. Data: the estimate with its totals and the answer.
Time
time_entry.created Time entry created
A new entry: the timesheet, the Week grid, a stopped timer, the dashboard, the API or MCP.
time_entry.updated Time entry updated
A change of one entry, also "Mark as not billed" and the restore of a write-off.
time_entry.deleted Time entry deleted
A delete of one entry. Data: the entry before the delete.
time_entries.bulk_changed Time entries changed in bulk
Many entries at once. Data: a summary of the change (see "Bulk changes").
Expenses
expense.created Expense created
A new expense.
expense.updated Expense updated
A change of one expense, also a removed receipt and "Mark as not billed".
expense.deleted Expense deleted
A delete of one expense. Data: the expense before the delete.
expenses.bulk_changed Expenses changed in bulk
Many expenses at once. Data: a summary of the change (see "Bulk changes").
Payload
One event in each request. Its id is the same for each webhook that gets it. data is the record as it was at the change, with every amount and cost, in the shape of the API. A receiver that needs the record of now reads it through the API.
{
"id": "0193a5b2-…",
"type": "time_entry.created",
"created_at": "2026-11-13T04:05:06Z",
"workspace_id": "0193a5b0-…",
"data": {
"id": "0193a5b1-…",
"spent_on": "2026-11-13",
"hours": "2.00"
}
}
Bulk changes
A write that changes many entries or expenses at once sends one time_entries.bulk_changed and one expenses.bulk_changed, never one event for each record. data has kind, from and to, count, member_ids, project_ids and ids (at most 1000). Past the cap, ids_truncated is true: read the range again with GET /api/v1/time_entries or GET /api/v1/expenses, in windows of at most 366 days, both dates included (the range of an import can be years), and follow next_page in each window.
import
An import of a Harvest account or of CSV files: one event of each type for the run.
rate_change
"Update existing time" of a rate change, and a new cost rate of a teammate.
approval
An approve or a reopen of a week, and the turn-on of the approvals.
invoice_attach
A save of a draft invoice that takes entries or expenses.
invoice_detach
A save of a draft that leaves entries or expenses, a revert or a delete of an invoice, a credit note.
write_off
"Write off" of the uninvoiced time of a project.
An import is history: its invoices, payments and estimates send no invoice or estimate event.
Signature
Hourbun-Event
The type of the event.
Hourbun-Delivery
The id of the delivery: the same for each attempt and for a redelivery, so a receiver can skip one that it has.
Hourbun-Webhook-Id
The id of the webhook.
Hourbun-Signature
t=<unix time>,v1=<hex>: the HMAC-SHA256 of "<unix time>.<body>" with the secret as the key, in lower-case hex.
Check it with the exact bytes of the body, and refuse an old time:
import hmac, hashlib, time
def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
parts = dict(part.split("=", 1) for part in header.split(","))
timestamp = int(parts["t"])
expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
return abs(time.time() - timestamp) <= tolerance and hmac.compare_digest(expected, parts["v1"])
Retries
Any 2xx answer is a success. A failed delivery is tried again, 10 attempts in about a day; a redirect is a failure. A webhook that fails for 3 days is disabled, and the Settings tab says why.
Not in the API yet
- An Idempotency-Key header: a POST that is sent twice tracks its time twice.
- Writes of clients, projects, tasks, invoices, estimates and expenses; reads of estimates and of the payments of an invoice (an invoice gives its paid amount and its balance); the receipt files of expenses.
- The webhooks themselves: add and change them in the app.