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, 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
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
update_task	A Clocktopus task's title, summary or kind, or cancel it. 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_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 tasks with create_task, unless the repository's agent instructions (CLAUDE.md, AGENTS.md or a contributing guide) say to create them in another tracker: then it creates them there, through that tracker's own MCP server. Connecting Linear or Jira alone doesn't change where. The agent skills follow the same rule.

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.