Skip to main content
Glama

Timetastic MCP

An unofficial MCP server for Timetastic, exposing the Timetastic API to agentic clients so they can query and manage absence & leave data.

Setup

You need an admin API token, generated at https://app.timetastic.co.uk/api. The server reads it from the TIMETASTIC_API_TOKEN environment variable.

The quickest way to run it is with uv's uvx, which fetches and runs the published package without a manual install:

export TIMETASTIC_API_TOKEN="your-token-here"
uvx timetastic-mcp

Or install it as a tool so the timetastic-mcp command is on your PATH:

uv tool install timetastic-mcp   # or: pipx install timetastic-mcp
IMPORTANT

Only admin users can generate API tokens on Timetastic. The above URL is only accessible to admin users.

Related MCP server: Tweek MCP Server

Client configuration

Add the server to your MCP client (e.g. Claude Desktop / Claude Code):

{
  "mcpServers": {
    "timetastic": {
      "command": "uvx",
      "args": ["timetastic-mcp"],
      "env": { "TIMETASTIC_API_TOKEN": "your-token-here" }
    }
  }
}

Pin a version with "args": ["timetastic-mcp@0.1.0"]. If you installed the command on your PATH instead, use "command": "timetastic-mcp" with "args": []. In Claude Code you can also add it from the CLI:

claude mcp add timetastic --env TIMETASTIC_API_TOKEN=your-token -- uvx timetastic-mcp

Tools

Tools are grouped by resource and named <verb>_<resource>.

Group

Tools

Absences

list_absences

Holidays (leave bookings)

list_holidays, get_holiday, book_holiday, action_holiday

Users

list_users, get_user, get_user_contact, add_user, edit_user, archive_user, restore_user, assign_public_holidays_to_user

Departments

list_departments, get_department, add_department, edit_department, delete_department

Leave types

list_leave_types, get_leave_type, list_leave_type_colors, list_leave_type_icons, create_leave_type, update_leave_type, delete_leave_type

Allowances

list_all_allowances, get_user_allowance, update_user_allowance, update_user_carry_forward, add_user_toil, update_user_toil, delete_user_toil

Locked dates

list_locked_dates, add_locked_date, delete_locked_date

Public holidays

list_public_holidays, get_public_holiday, list_public_holiday_countries

Webhooks

list_webhook_events

Note: Timetastic calls all leave bookings "holidays" for historical reasons — the Holidays tools cover any kind of absence, not just annual leave.

Layout

The package lives under src/timetastic_mcp/:

  • timetastic.py — async HTTP client (auth, base URL, rate-limit retries, error handling).

  • server.py — the shared FastMCP instance and get_client(), the lazily-created API client the tools call.

  • tools/ — one module per resource area, each registering its tools on the shared server: absences, holidays, users, departments, leave_types, allowances, locked_dates, public_holidays, webhooks.

  • main.py — entry point (the timetastic-mcp console script); imports tools to register everything, then runs the server.

Development

Requires Python 3.13+ and uv.

uv sync           # create the venv and install the package + dev deps
uv run pytest     # run the test suite
uv run timetastic-mcp   # run the server from your checkout

Notes

  • The API is rate limited to 5 requests/second per token (1/second for list_absences); the client retries once on a 429.

  • Write and admin operations require appropriate permissions on the token's user account.

Available Tools

39 tools
action_holidayA

Approve, decline or cancel a holiday.

Args: holiday_id: The holiday ID (or a holiday token). action: Approve, Decline, Delete (cancel this booking) or DeleteGroup (cancel the whole group booking). reason: Optional reason, typically used when declining/cancelling. suppress_emails: Suppress notification emails when actioning.

Raises a webhook event if webhooks are configured.

Inputs: action (required), holiday_id (required), reason, suppress_emails.

add_departmentB

Create a new department.

Args: name: The department name. manager_id: User ID of the department manager. max_off: Max number of users off at once (0 = no limit).

Inputs: name (required), manager_id (required), max_off.

add_locked_dateA

Add a locked date period.

Args: from_date: Start of the locked period (ISO 8601 date-time). to_date: End of the locked period (ISO 8601 date-time). reason: Reason for the lock (1–2000 chars). record_type: Scope of the lock: Organisation, Department or User. Higher-level locks supersede lower-level ones. record_id: The organisation, department or user ID the lock targets.

Inputs: reason (required), to_date (required), from_date (required), record_id (required), +1 more.

add_userA

Add a new user to Timetastic.

Args: first_name: The user's first name. last_name: The user's last name. department_id: The department to place the user in. allowance: Annual leave allowance in days (0–366). email_address: The user's email address. start_date: Start date, ISO 8601 (e.g. 2022-02-04T00:00:00). leave_year_start: Month the leave year starts (1=Jan … 12=Dec). send_welcome_email: Email the user to set a password and get started.

Inputs: allowance (required), last_name (required), first_name (required), department_id (required), +4 more.

add_user_toilA

Add a TOIL (time off in lieu) entry for a user in a year.

Args: user_id: The user to add TOIL for. year: The year the TOIL applies to. amount: TOIL amount (-5000 to 5000). description: Optional description (max 1000 chars).

Returns the ID of the new TOIL entry.

Inputs: year (required), amount (required), user_id (required), description.

archive_userA

Archive a user. They are logged out immediately and cannot log in.

Args: user_id: The ID of the user to archive. archive_date: The date the user left (UTC, must be in the past), ISO 8601. Shown on their archived profile and in reports.

Inputs: user_id (required), archive_date.

assign_public_holidays_to_userA

Assign a set of public holidays to a user (enabling them if needed).

Args: user_id: The user's ID. country_code: ISO 3166-1 alpha-2 country code (e.g. "ES" for Spain). region_code: Full region code (e.g. "GB-SCT" for Scotland, "ES-AN" for Andalucía).

If the chosen country/region is already used by your organisation, that (possibly customised) set is used; otherwise the standard set is assigned.

Inputs: user_id (required), region_code, country_code.

book_holidayA

Submit a leave request (book time off).

Args: from_date: Start date YYYY-MM-DD (no time component). to_date: End date YYYY-MM-DD (no time component). leave_type_id: The leave type to book (see list_leave_types). book_for: User, Department or Everyone. user_or_department_id: ID of the user/department to book for (with book_for). Omit to book for yourself. from_time: Part of the start day: "AM", "PM", or minutes since midnight for an hourly booking. to_time: Part of the end day: "AM", "PM", or minutes since midnight for an hourly booking. reason: Optional reason for the request. suppress_emails: Admins only — suppress notification emails. book_as_requestee: Admins only — book as if the requestee made it so the normal approval flow runs (default is auto-approved by the admin). override: Admins only — bypass the department max-off limit. override_locked_days: Admins only — book over locked dates. override_accrued_allowance: Admins only — bypass accrued-allowance check. attachment_id: Attach a previously uploaded attachment by ID.

Inputs: to_date (required), from_date (required), leave_type_id (required), reason, +10 more.

create_leave_typeA

Create a new leave type (admins only).

Args: name: Name of the leave type (1–50 chars). deducted: Whether it deducts from the user's allowance. requires_approval: Whether bookings need approval. include_max_off: Whether it counts toward max-absent limits. is_private: Whether the leave type is private. color: A hex colour (see list_leave_type_colors). icon: An icon name (see list_leave_type_icons). calendar_visibility: Busy, Available or OutOfOffice. limit_hours: Optional limit in hours. limit_days: Optional limit in days.

Returns the ID of the new leave type.

Inputs: name (required), icon, color, deducted, +6 more.

delete_departmentA

Delete a department. It must be empty (reassign any users first).

Inputs: department_id (required).

delete_leave_typeA

Delete (deactivate) a leave type. Cannot delete the last active one.

Inputs: leave_type_id (required).

delete_locked_dateB

Delete a locked date by ID (admins/authorised managers only).

Inputs: locked_date_id (required).

delete_user_toilC

Delete a user's TOIL entry.

Inputs: year (required), toil_id (required), user_id (required).

edit_departmentB

Edit a department. Only the fields you supply are changed.

Args: department_id: The department to edit. name: New department name. manager_id: User ID of the department manager. max_off: Max users off at once (0 disables the limit; range 0–20).

Inputs: department_id (required), name, max_off, manager_id.

edit_userB

Edit a user. Only the fields you supply are changed (partial update).

Args: user_id: The ID of the user to edit. email_address: New email. Pass "" to clear an existing address. approver_id: The user's approver; set to 0 to default to dept manager. public_holiday_set_id: Public holiday set (needs has_public_holidays). has_public_holidays: Enable public holidays for this user. (Other args map directly to the corresponding user fields.)

Inputs: user_id (required), city, admin, country, +19 more.

get_departmentC

Get a single department by ID.

Inputs: department_id (required).

get_holidayB

Get a single holiday (leave booking) by its ID.

Inputs: holiday_id (required), filter.

get_leave_typeC

Get a single leave type by ID.

Inputs: leave_type_id (required).

get_public_holidayC

Get a single public holiday by ID.

Inputs: public_holiday_id (required).

get_userB

Get a user by ID, including work schedule and allowance breakdown.

Inputs: user_id (required).

get_user_allowanceA

Get allowances, TOIL and carry-forward for one user.

Args: user_id: The user to query. year: Restrict to a single year. Omit for all years.

Inputs: user_id (required), year.

get_user_contactB

Get a user with contact-tab details (address, phone, emergency contact).

Requires a Timetastic Pro account.

Inputs: user_id (required).

list_absencesA

Get a chronological list of who is off between two dates.

The single best endpoint for "who is off on/around a given day" — it merges bookings, non-working days, public holidays and (optionally) other events without needing multiple queries.

Args: start: Start date, ISO format YYYY-MM-DD. end: End date, ISO format YYYY-MM-DD. Max 31 days after start. query_type: What to include. AllAbsences (bookings, public holidays and non-working days), Bookings, PublicHolidays or AllEvents (also birthdays, work anniversaries and locked dates).

Rate limited to 1 request per second; limited to a 31-day range.

Inputs: end (required), start (required), query_type.

list_all_allowancesA

List allowances, TOIL and carry-forward for all users.

Args: year: Restrict to a single year. Omit for all years.

Inputs: year.

list_departmentsA

List all departments in the organisation.

Inputs: no named parameters.

list_holidaysA

Query leave bookings ("holidays") for the organisation.

All filters are optional. Results are paginated at 100 per page — use page_number and read totalRecords/nextPageLink in the response.

Args: start: Include holidays on or after this date-time (ISO 8601). end: Include holidays before and including this date-time (ISO 8601). status: Filter by status. Defaults to pending + approved if omitted. user_ids: Comma-separated user IDs to include (e.g. "12,34"). exclusion_user_ids: Comma-separated user IDs to exclude. department_id: Only holidays for this department. leave_type_id: Only holidays of this leave type. approver_id: Only holidays approved by this user. my_team_only: Restrict to the team of this user ID. my_favourites_only: Restrict to the favourite users of this user ID. department_managers_only: Only holidays for department managers. non_archived_users_only: Exclude archived users. transaction_year: Filter to this transaction year. page_number: Page to fetch (defaults to 1).

Inputs: end, start, status, user_ids, +10 more.

list_leave_type_colorsA

List the valid colour hex codes for leave types.

Inputs: no named parameters.

list_leave_type_iconsA

List the valid icon names for leave types (empty string = no icon).

Inputs: no named parameters.

list_leave_typesB

List leave types for the organisation.

Args: include_inactive: Also return inactive (deleted) leave types.

Inputs: include_inactive.

list_locked_datesA

List all locked dates (periods where booking time off is blocked).

Inputs: no named parameters.

list_public_holiday_countriesA

List all countries available for public holidays.

Inputs: no named parameters.

list_public_holidaysB

List public holidays for the organisation.

Args: country_code: Filter to a country code. year: Filter to a year. user_id: Filter to a user's public holidays. bank_holiday_set_id: Filter to a bank holiday set. use_org_leave_year: Use the user's leave year instead of calendar year.

Inputs: year, user_id, country_code, use_org_leave_year, +1 more.

list_usersB

List users in the organisation, optionally filtered by department.

Args: department_id: Only users in this department. include_archived_users: Include archived users in the results. only_show_archived_users: If archived users are included, show ONLY them.

Inputs: department_id, include_archived_users, only_show_archived_users.

list_webhook_eventsA

List recent webhook events (up to 30 days of history are retained).

Args: days_history: How many days of history to return (defaults to 1).

Inputs: days_history.

restore_userA

Restore an archived user so they can use Timetastic again.

Inputs: user_id (required).

update_leave_typeC

Update an existing leave type (admins only). name is required.

Inputs: name (required), leave_type_id (required), icon, color, +7 more.

update_user_allowanceA

Set a user's annual allowance for a year.

Args: user_id: The user to update. year: The year to update. amount: The new allowance (0–8784).

Inputs: year (required), amount (required), user_id (required).

update_user_carry_forwardC

Set a user's carry-forward amount for a year (0–5000).

Inputs: year (required), amount (required), user_id (required).

update_user_toilC

Update an existing TOIL entry (-5000 to 5000).

Inputs: year (required), amount (required), toil_id (required), user_id (required), +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 39 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action (e.g., book vs approve vs list holidays, CRUD for users, departments, leave types, etc.). Descriptions are clear, and overlapping concepts are differentiated by purpose (e.g., list_absences vs list_holidays).

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., add_user, get_holiday, delete_leave_type). No mixing of conventions or irregular naming.

    Tool Count4/5

    At 39 tools, the set is larger than typical but justified by the comprehensive scope of leave management (users, departments, holidays, leave types, public holidays, TOIL, allowances, webhooks). Could be slightly consolidated but remains well-organized.

    Completeness5/5

    The tool set covers full lifecycle management: CRUD for all entities (users, departments, leave types, locked dates), booking and managing holidays, handling TOIL and allowances, public holidays, and even webhook events. No obvious gaps for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that wraps the TimePRO API, enabling AI assistants to automatically create, view, and manage timesheets for authenticated users. It provides tools for searching clients and projects, retrieving configuration defaults, and performing full CRUD operations on timesheet entries.
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that integrates with the Tweek API to manage calendars, tasks, and custom colors. It enables users to perform full task CRUD operations, list accessible calendars, and fetch color preferences through secure authentication.
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      A modular MCP server integrating Clockify, WakaTime, and Azure DevOps for time tracking, work item management, and time logging via a unified API.
      2
      -