MCP server

Clocktopus exposes a remote Model Context Protocol server, so an MCP-compatible assistant can answer questions from your tracked hours, see where each task stands, and create tasks as it works. It acts as you, so it sees and changes only what you can.

What you need

• A Clocktopus account. You sign in during the connection flow.
• An MCP client that supports remote servers over OAuth — anything offering "custom connectors" generally does.
• The server URL:

https://clocktopus.app/api/mcp

There are no API keys. Authorisation is OAuth 2.1: the client walks you through the same sign-in you use for the dashboard plus a one-time consent screen, so a connected assistant can only ever see what you can. Nothing to copy or paste.

Add the connector

The wording varies by client, but the flow does not.

1. In your client's connector settings, add a custom (remote) MCP server.
2. Enter the server URL. Leave any optional OAuth Client ID / Secret fields blank — the client registers itself.
3. A browser window opens to Clocktopus. Sign in if you are not already, then approve the access request.
4. Ask it something: "Using Clocktopus, list my projects", or "how many hours did I track per task on Public Website in May?"

What it can do

Tool	What it does
list_organisations, list_projects	Your organisations and the projects you can write to
get_task_hours, get_project_task_hours	Hours per task, over a range or all time
get_repository_context	For a repository's remote URL: its project, task key prefix, delivery branches, connected trackers and the tracker each declared prefix belongs to, how many tasks are open, the ones in progress or in review, and the task the current branch names
search_tasks	Finds tasks in the repository's project, and tracker tasks no project has claimed yet, by words in their key, title or summary (best match first, typos tolerated), stage, goal, kind or last update, a page at a time
get_task	One task by key: its summary, stage, kind, refined mark, pull requests, agent sessions and cost so far, who reported it and who worked on it
create_task	A task in the repository's project, with a key such as CLK-12, a branch name that starts with it, and optionally its kind: bug, feature, improvement or tech
register_ticket	A Linear or Jira ticket your agent read through the tracker's own MCP server, recorded in the repository's project under its own key, with its title, summary, link, kind and creation date, whether or not the tracker is connected. Calling it again re-syncs them, and its key when the ticket moved
update_task	A Clocktopus task's title, summary or kind, or cancel it; a task a branch or commit created by its key can be cancelled too. Marks any task as refined (refined: true) once its open questions are settled. Anything else on a Linear or Jira task is changed in the tracker
link_session	Ties the current agent session to a task, so its time and spend count toward it whatever branch or directory the session is in. Without a session id, it ties your one live session in the repository
get_session_panel	For one of your own agent sessions: the task it counts toward, with its stage, hours and page, its spend per task, that task's active goal, and, given the CLI's version, where that CLI stands against the latest and the oldest the server serves. Ties the session to its branch's task the first time it names one
get_ticket_flow	For any task keys: the stage, its kind and refined mark, its pull requests, its agent sessions, and its cost so far: hours, people at cost rates, agent spend (stages)
create_goal, update_goal, list_goals	Goals in the repository's project: an outcome to reach, and whether it is active or closed
plan_goal	A goal's tasks as done, open (in order) and cancelled, with their stage, kind, refined mark and what needs attention, and the project's other open tasks ranked against it
set_goal_tasks	A goal's tasks and their order: replace the list (tasks), add to its end (add), or release tasks from it (release)
next_task	The first open, unstarted task in a goal's order, with a branch name, and every open one with whether it is started

A task's kind is bug, feature, improvement or tech: a Linear or Jira task takes it from its labels or issue type, and a Clocktopus task from create_task or update_task. Refined is Clocktopus's own mark that a task's open questions are settled and written into it; it is never sent to Linear or Jira.

An agent creates a task where the repository's agent instructions (CLAUDE.md, AGENTS.md or a contributing guide) say. When they don't say, the project's tracker key prefixes decide: if one of them belongs to a connected Linear or Jira, the agent creates the task in that tracker, through the tracker's own MCP server, and registers it at once with register_ticket, so it is in Clocktopus before the tracker's webhook arrives. A prefix belongs to a tracker once a ticket with it arrives or is registered with the tracker's issue id. When several prefixes belong to connected trackers, the agent asks which one. With none connected, it creates the task in Clocktopus with create_task, saying why it didn't use the tracker: it isn't connected, or no ticket with the prefix has arrived yet. When the tracker's MCP server isn't available, it offers Clocktopus instead.

register_ticket also brings in a ticket from a tracker Clocktopus isn't connected to: the agent reads it through the tracker's MCP server and records it under its own key, so its commits, pull requests and agent spend count toward it. The key's prefix must be one the project declares, or one a connected tracker's tickets use; a key with the project's own prefix is refused. Given the tracker's issue id (externalId), the task carries it, so a webhook from that tracker, once connected, updates the same task; without one, the task is held by its key until a connected tracker's ticket takes it over. Calling it again replaces the title, summary, link and kind, which update_task never changes on a tracker's task. A registered ticket from a tracker that isn't connected counts toward its own project only: its prefix lets no other project's commits create tasks, and plan_goal never flags it delivered_tracker_open, since no completion arrives for it. The agent skills follow the same rule.

A Clocktopus task's key starts with its project's task key prefix, and the project's tracker key prefixes say which trackers its tickets come from.

A task's stage is never set through the connector: it moves on its own from commits, pull requests and delivery.

A task's summary is Markdown, shown formatted on the Tasks page. The server tells every connected assistant so, and how to lay one out: the problem, why it matters, what to do and what is out of scope. Assistants that don't use the agent skills then write tasks the same way as those that do.

Goals

A goal takes the place of a sprint or cycle. It is an outcome, such as "customers can export invoices", with no dates, so unfinished tasks never roll over: they stay in the goal until it is closed or they are released from it. Its tasks are named by key, so Linear, Jira and Clocktopus tasks mix freely.

• Each goal has a number in its organisation, shown on its card as G-3. Every goal tool takes it as goalId in place of the goal's id; pass orgId as well when you belong to several organisations.

• A goal is one ordered list of tasks, the order to work them in. The goal is reached once every one of them is delivered. Each task is in one of three states:

  • Done: its pull request merged. This follows from its stage, so nothing moves it there by hand.
  • Open: not finished yet, in the goal's order, shown as To do on the goal's card. next_task hands out the first one that nothing has started yet (no linked agent session, commit or pull request), so sessions running side by side each take a different task. When nothing in the goal is open, next_task answers next_empty.
  • Cancelled: counts toward nothing until it is released.

• Replacing the list keeps what is done. set_goal_tasks with tasks replaces the goal's list; an open or cancelled task left out is released from the goal, while a done one stays unless it is named in release. add appends tasks to the end and leaves one already in the goal where it is. next, toPlan and later, from older skills, add their tasks the same way.

• A goal is finished with a task once its pull request merges: delivery to a delivery branch follows on its own. The task's own stage still moves to delivered as everywhere else in Clocktopus. plan_goal flags a task delivered but still open in its tracker, one closed in its tracker but not delivered, one with no new stage for seven days, and a key nothing has seen.

• A goal closes itself once every task in it that isn't cancelled has reached a delivery branch. update_goal, or Close goal on the goal's card, closes one by hand; update_goal also reopens it; a reopened goal closes itself again only when one of its tasks is delivered or cancelled after the reopen.

Good to know

Scoped to you. The connector reads what your account can already see, and writes only tasks and goals, in projects you can log time on. It never edits time entries, projects or members.

Revoke any time. Remove the connector in your MCP client and the issued token expires.

Dates are YYYY-MM-DD. Check the year — a mismatched range is the usual reason totals look wrong.