timetastic-mcp
This server provides an MCP interface for the Timetastic API, enabling agentic clients to query and manage absence, leave, and related workforce data.
Absences
List who is off between specified dates (up to 31 days), merging bookings, public holidays, non-working days, and other events.
Leave Bookings (Holidays)
List holidays with rich filtering (date, status, user, department, leave type, approver, etc.) with pagination
Get a single holiday by ID
Book leave (including half-days, hourly bookings, admin overrides) for yourself, a department, or everyone
Approve, decline, or cancel individual or group bookings
Users
List, get, add, edit, archive, and restore users
Get user contact details (Pro accounts only)
Assign public holidays to a user by country/region
Departments
List, get, create, edit, and delete departments
Leave Types
List, get, create, update, and delete leave types
List valid colors and icons for leave types
Allowances
List allowances, carry-forward, and TOIL for all users or a specific user
Update annual allowances and carry-forward amounts
Add, update, and delete TOIL (Time Off In Lieu) entries
Locked Dates
List, add, and delete locked date periods (scoped to organisation, department, or user)
Public Holidays
List public holidays (filterable by country, year, or user), get a specific holiday, and list available countries
Webhooks
List recent webhook events (up to 30 days of history)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@timetastic-mcp list upcoming holidays for Jane Doe"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpOr install it as a tool so the timetastic-mcp command is on your PATH:
uv tool install timetastic-mcp # or: pipx install timetastic-mcpOnly 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-mcpTools
Tools are grouped by resource and named <verb>_<resource>.
Group | Tools |
Absences |
|
Holidays (leave bookings) |
|
Users |
|
Departments |
|
Leave types |
|
Allowances |
|
Locked dates |
|
Public holidays |
|
Webhooks |
|
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 sharedFastMCPinstance andget_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 (thetimetastic-mcpconsole script); importstoolsto 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 checkoutNotes
The API is rate limited to 5 requests/second per token (1/second for
list_absences); the client retries once on a429.Write and admin operations require appropriate permissions on the token's user account.
Available Tools
39 toolsaction_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
Scored across 39 tools
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).
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.
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.
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
Related MCP Connectors
MCP server providing attendance data queries via the CloudTime API.
timesheet.io MCP server - manage timers, projects, tasks and reports
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn 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.10MIT
- AlicenseNot gradedqualityDmaintenanceAn 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.1MIT
- FlicenseNot gradedqualityCmaintenanceA modular MCP server integrating Clockify, WakaTime, and Azure DevOps for time tracking, work item management, and time logging via a unified API.2-
- AlicenseAqualityBmaintenanceA read-only MCP server for querying Timely time tracking data, providing tools for project overviews, time spent summaries, and work log entries.3MIT