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

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>.

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.