MCP tools: Time tracking and calendar

Track time, start and stop timers, correct entries, read and create Google Calendar events and find shared free slots across the team.

Prerequisites
  • Time tracking or Calendar module enabled.
  • For calendar tools: a connected Google Calendar (for find_team_free_slots additionally colleagues who share their availability).

list_time_entries

Lists time entries of the organization, latest start first; filter by project and task. Requirements: role Viewer or higher, key scope "read" or higher, module "Time tracking" enabled.

projectId
Optional · string — Only entries of this project.
taskId
Optional · string — Only entries for this task.
limit
Optional · number — Maximum number of results (default 50, max 200).

get_running_timer

Returns your currently running time entry (no end time) in the organization, or null if none is running. Requirements: role Viewer or higher, key scope "read" or higher, module "Time tracking" enabled. This tool takes no parameters.

create_time_entry

Logs a time entry for you. Without endTime a running timer is started; otherwise the duration in seconds is computed from start and end. The tool does not check whether a timer is already running. Requirements: role Member or higher, key scope "write" or higher, module "Time tracking" enabled.

startTime
Required · string — Start as ISO 8601 datetime.
endTime
Optional · string — End (ISO 8601). Omit to start a running timer.
description
Optional · string — Description of the work.
projectId
Optional · string — ID of the assigned project.
taskId
Optional · string — ID of the related task.

stop_timer

Stops your running timer and computes the duration. Your running entry is looked up without restricting it to the organization. If there is none, the error "No running timer found" is returned. Requirements: role Member or higher, key scope "write" or higher, module "Time tracking" enabled.

endTime
Optional · string — End (ISO 8601). Default: now.

update_time_entry

Updates a time entry (description, times, project, task) and recomputes the duration. Entries whose billing status is reserved or billed are locked. Requirements: role Member or higher, key scope "write" or higher, module "Time tracking" enabled.

id
Required · string — ID of the time entry.
startTime
Optional · string — New start (ISO 8601).
endTime
Optional · string — New end (ISO 8601).
description
Optional · string — New description.
projectId
Optional · string — ID of the assigned project.
taskId
Optional · string — ID of the related task.

delete_time_entry

Deletes a time entry. Requires at least the Admin role and a key with the delete scope. Reserved or billed entries cannot be deleted. Requirements: role Admin or higher, key scope "delete" or higher, module "Time tracking" enabled.

id
Required · string — ID of the time entry.

list_calendar_events

Lists upcoming events from the current user's connected Google Calendar and Outlook calendar (Google under events, Outlook under outlook.events). If no calendar is connected, the tool answers with connected=false and a message instead of an error. Internal-only appointments are listed by list_meetings. Requirements: role Viewer or higher, key scope "read" or higher, module "Calendar" enabled.

maxResults
Optional · number · Default: 20 — Maximum number of events (default 20, max 50).

create_calendar_event

Creates an event. Pick the target with calendar: google, outlook or internal (app only); auto uses the connected Google calendar, else Outlook, else internal. Files can be passed as attachments and are also attached to the Google/Outlook event (Google via Drive, Outlook up to 3 MB, otherwise a link in the description). Ticket numbers and context belong in the description (notes). Requirements: role Member or higher, key scope "write" or higher, module "Calendar" enabled.

title
Required · string — Event title.
startDateTime
Required · string — Start as ISO 8601 datetime with UTC offset or Z, e.g. 2026-07-01T10:00:00+02:00.
endDateTime
Required · string — End as ISO 8601 datetime with UTC offset or Z, e.g. 2026-07-01T11:00:00+02:00.
description
Optional · string — Optional event description.
addMeet
Optional · boolean · Default: false — Adds an online meeting link to the event (Google Meet or Teams).
calendar
Optional · string · auto | google | outlook | internal · Default: auto — Target calendar: google, outlook or internal (app only).
calendarId
Optional · string — Specific Google/Outlook calendar id. Default: the calendar starred in the calendar settings.
attachments
Optional · array — Up to 5 files (10 MB each) as objects with name plus text or contentBase64 (and optionally mimeType). Text suits summaries and ticket lists, base64 only small binary files.

update_calendar_event

Edits an existing event in the connected Google or Outlook calendar. Only the fields you pass change. source, eventId and calendarId come from list_calendar_events. Events that create_calendar_event created with the meetings module are app meetings: change those with update_meeting. Requirements: role Member or higher, key scope "write" or higher, module "Calendar" enabled.

source
Required · string — Which calendar: google or outlook.
eventId
Required · string — The event id from list_calendar_events.
calendarId
Optional · string — The event calendarId from list_calendar_events (for events outside the primary calendar).
title
Optional · string — New title.
startDateTime
Optional · string — New start, ISO 8601 with UTC offset or Z.
endDateTime
Optional · string — New end, ISO 8601 with UTC offset or Z.
description
Optional · string — Replaces the event notes.
location
Optional · string — Location.
notifyGuests
Optional · boolean — Google only: send update mails to guests (default false).

add_event_attachment

Attaches a file to an existing Google or Outlook event after the fact. The file is stored in the organization (and shown in the event's file list in the calendar) and attached to the provider event (Google via Drive, Outlook up to 3 MB, otherwise a note in the description). Real files go through create_attachment_upload_url with source/eventId. App meetings use add_meeting_attachment. Requirements: role Member or higher, key scope "write" or higher, module "Calendar" enabled.

source
Required · string — Which calendar: google or outlook.
eventId
Required · string — The event id from list_calendar_events.
calendarId
Optional · string — The event calendarId from list_calendar_events (for events outside the primary calendar).
name
Required · string — File name with extension.
mimeType
Optional · string — MIME type, e.g. application/pdf.
text
Optional · string — Text content of the file.
contentBase64
Optional · string — File content as base64 (small files only).

list_event_attachments

Lists the files attached in the app to a Google or Outlook event. Requirements: role Viewer or higher, key scope "read" or higher, module "Calendar" enabled.

source
Required · string — Which calendar: google or outlook.
eventId
Required · string — The event id from list_calendar_events.
calendarId
Optional · string — The event calendarId from list_calendar_events (for events outside the primary calendar).

find_team_free_slots

Finds the earliest upcoming free time slots you share with your teammates – connected Google, Outlook and iCal calendars are considered, and only members who opted in to sharing availability. Returns slots and consideredTeammates. Requires an organization context. Requirements: role Viewer or higher, key scope "read" or higher, module "Calendar" enabled.

durationMin
Optional · number · Default: 30 — Slot length in minutes.
days
Optional · number · Default: 10 — How many calendar days ahead to search (max 45).
maxResults
Optional · number · Default: 5 — Maximum number of slots (max 20).
startHour
Optional · number · Default: 9 — Start of business hours in local time (0–23).
endHour
Optional · number · Default: 18 — End of business hours in local time (0–23).
teammateUserIds
Optional · string[] — Restricts the search to these teammates (Supabase user IDs) instead of everyone who shares availability.

Common pitfalls

  • Send times with an offset

    Send times as ISO 8601 with UTC offset or Z (e.g. 2026-09-26T09:00:00+02:00). Without an offset the interpretation depends on the server setting.

  • Timers are per person

    get_running_timer and stop_timer refer to your timer. stop_timer looks it up without restricting it to the organization.

  • Locked entries

    Reserved or billed time entries can be neither changed nor deleted. A running timer is not checked on creation: create_time_entry starts another one even if one is already running.

  • Calendar not connected

    list_calendar_events reports connected=false, create_calendar_event returns an error. Connect the calendar in the web app first.

Keep reading

Still have a question or a problem?

Visit support

Last reviewed on 2026-09-26