when-i-work
Check shifts, time clock entries, time-off requests, swaps and availability, and manage shifts.
Should I use this
Quality & Safety
A
Findings (4)
- LOWTool 'wheniwork_list_eligible_users_for_shift' name length outside 3-30 rangein wheniwork_list_eligible_users_for_shift
- LOWTool 'wheniwork_list_time_off_requests' name length outside 3-30 rangein wheniwork_list_time_off_requests
- LOWTool 'wheniwork_create_time_off_request' name length outside 3-30 rangein wheniwork_create_time_off_request
- LOWTool 'wheniwork_update_time_off_request' name length outside 3-30 rangein wheniwork_update_time_off_request
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
~5,727Tokens (tool definitions)
~2.1 KBTypical response size
Significant attention impact (4.47% of 128k context)
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"when-i-work": {
"url": "https://when-i-work.usefulapi.io/mcp"
}
}
}Remote endpoints
https://when-i-work.usefulapi.io/mcpstreamable-httpWhat it can do
Tool inventory
Tools (21)
🟢 Read-only🟡 Write🔴 Delete⚪ Unknown
🟢wheniwork_get_account
Fetch the When I Work account (workplace) the token acts on — company name, plan and settings; for a parent account also its child accounts. A cheap way to confirm the credentials work. When I Work: GET /2/account.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_users(location_id, search, show_pending, only_pending, show_deleted, ...)
List the employees, supervisors, managers and admins in the account, optionally limited to some schedules or searched by name/email. Role codes: 1 admin, 2 manager, 3 employee, 5 supervisor. When I Work: GET /2/users.
Input Schema
{
"type": "object",
"properties": {
"location_id": {
"description": "One or more schedule (location) ids.",
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"search": {
"description": "Search first name, last name or email.",
"type": "string"
},
"show_pending": {
"description": "Include users who have not accepted their invite (default true).",
"type": "boolean"
},
"only_pending": {
"description": "Only pending users.",
"type": "boolean"
},
"show_deleted": {
"description": "Include deleted users (supervisor or above).",
"type": "boolean"
},
"only_deleted": {
"description": "Only deleted/archived users (supervisor or above).",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_get_user(user_id)
Fetch one user by id — name, email, role, positions, schedules, wage. When I Work: GET /2/users/{id}.
Input Schema
{
"type": "object",
"properties": {
"user_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The user id."
}
},
"required": [
"user_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_locations(only_unconfirmed)
List the schedules in the account. The API calls a schedule a "location"; its id is the location_id every shift belongs to. When I Work: GET /2/locations.
Input Schema
{
"type": "object",
"properties": {
"only_unconfirmed": {
"description": "Only schedules whose address is unconfirmed.",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_positions(show_deleted)
List the positions (job roles such as Cashier or Dishwasher) in the account. When I Work: GET /2/positions.
Input Schema
{
"type": "object",
"properties": {
"show_deleted": {
"description": "Include deleted positions.",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_shifts(start, end, user_id, location_id, all_locations, ...)
List scheduled shifts in a time window — who works when, where and in which position — optionally including open shifts and unpublished drafts. Answers "who is on on Friday?" and "what open shifts are left?". When I Work: GET /2/shifts.
Input Schema
{
"type": "object",
"properties": {
"start": {
"description": "Start of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"end": {
"description": "End of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"user_id": {
"description": "Only this user's shifts.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"location_id": {
"description": "One or more schedule (location) ids.",
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"all_locations": {
"description": "Include shifts from all schedules.",
"type": "boolean"
},
"unpublished": {
"description": "Include unpublished (draft) shifts — supervisor or above.",
"type": "boolean"
},
"include_open": {
"description": "Include open (unassigned) shifts from the user's schedules.",
"type": "boolean"
},
"include_onlyopen": {
"description": "Return only open shifts.",
"type": "boolean"
},
"include_allopen": {
"description": "Include open shifts across all schedules — manager or admin.",
"type": "boolean"
},
"include_swaps": {
"description": "Include swap requests attached to the shifts.",
"type": "boolean"
},
"deleted": {
"description": "Also return deleted_ids: shifts deleted in the window.",
"type": "boolean"
},
"include_repeating_shifts_to": {
"description": "Also expand repeating shift series up to this date. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"limit": {
"description": "Maximum number of results.",
"type": "integer",
"minimum": 1,
"maximum": 1000
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_get_shift(shift_id, include_repeating_shifts_to)
Fetch one shift by id, including its breaks and publish state. When I Work: GET /2/shifts/{id}.
Input Schema
{
"type": "object",
"properties": {
"shift_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The shift id."
},
"include_repeating_shifts_to": {
"description": "Also expand the shift's repeating series up to this date. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
}
},
"required": [
"shift_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_eligible_users_for_shift(shift_id, start, end, position_id, location_id, ...)
Find who could take an open shift — either an existing shift (shift_id) or a hypothetical one (start, end, position_id and location_id all required). When I Work: GET /2/shifts/eligible.
Input Schema
{
"type": "object",
"properties": {
"shift_id": {
"description": "An existing shift's id.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"start": {
"description": "Start of the potential shift (required without shift_id). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"end": {
"description": "End of the potential shift (required without shift_id). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"position_id": {
"description": "Position of the potential shift (required without shift_id).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"location_id": {
"description": "Schedule of the potential shift (required without shift_id).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"is_shared": {
"description": "Whether it is a shared open shift.",
"type": "boolean"
},
"include_objects": {
"description": "Include the users' schedules and positions in the output.",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_times(start, end, user_id, only_open, updated_at)
List clocked time entries — actual hours worked, clock-in/out times, length and approval state. Use only_open to see who is clocked in right now. When I Work: GET /2/times.
Input Schema
{
"type": "object",
"properties": {
"start": {
"description": "Start of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"end": {
"description": "End of the window. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"user_id": {
"description": "One or more user ids.",
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"only_open": {
"description": "Only times with no end yet (people currently clocked in).",
"type": "boolean"
},
"updated_at": {
"description": "Only times updated since this timestamp. Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_time_off_requests(start, end, user_id, location_id, status, ...)
List time-off requests in a date range, with the requesting users. Status: 0 pending, 1 canceled, 2 accepted, 3 expired, 4 denied. When I Work: GET /2/requests.
Input Schema
{
"type": "object",
"properties": {
"start": {
"description": "Start date, yyyy-mm-dd.",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"end": {
"description": "End date, yyyy-mm-dd.",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"user_id": {
"description": "One or more user ids.",
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"location_id": {
"description": "Only requests for this schedule.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"status": {
"description": "Only requests with this status.",
"type": "integer",
"minimum": 0,
"maximum": 4
},
"type": {
"description": "Only this request type.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"sortby": {
"description": "'created' sorts newest first; anything else sorts by status then last update.",
"type": "string"
},
"include_deleted_users": {
"description": "Include requests made by deleted users.",
"type": "boolean"
},
"since_id": {
"description": "Only requests created after this request id.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"max_id": {
"description": "Only requests created before this request id.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"limit": {
"description": "Maximum number of results.",
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"page": {
"description": "Page of results to load (the response says whether there are `more`).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_get_time_off_request(request_id)
Fetch one time-off request by id, with its message thread and users. When I Work: GET /2/requests/{request_id}.
Input Schema
{
"type": "object",
"properties": {
"request_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The time-off request id."
}
},
"required": [
"request_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_time_off_types
List the time-off types (e.g. Personal, Sick, Holiday) and whether each allows paid time. Their ids are the type_id for a new request. When I Work: GET /2/requesttypes.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_shift_swaps(start, end, user_id, shift_id, status, ...)
List shift requests: swaps, drops and alerts, with the shifts and users involved. Status: 0 pending, 1 approved, 2 declined, 3 completed, 4 canceled, 5 expired. Type: 1 swap, 2 drop, 3 alert. start and end must be given together. When I Work: GET /2/swaps.
Input Schema
{
"type": "object",
"properties": {
"start": {
"description": "Start of the shift window (give with end). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"end": {
"description": "End of the shift window (give with start). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"user_id": {
"description": "One or more user ids.",
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"shift_id": {
"description": "One or more shift ids.",
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"status": {
"description": "One or more statuses.",
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 5
}
},
"type": {
"description": "One or more types.",
"minItems": 1,
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"maximum": 3
}
},
"open_only": {
"description": "Only open swaps.",
"type": "boolean"
},
"limit": {
"description": "Maximum number of results.",
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"page": {
"description": "Page of results to load (the response says whether there are `more`).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_availability(start, end, user_id, include_all)
List availability events — when people said they can or cannot work, including recurring patterns that fall in the window. Defaults to the caller, from now to two weeks out. When I Work: GET /2/availabilityevents.
Input Schema
{
"type": "object",
"properties": {
"start": {
"description": "Start of the window (default now). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"end": {
"description": "End of the window (default two weeks from now). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"user_id": {
"description": "Whose availability (default the calling user).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"include_all": {
"description": "Everyone's availability, not just one user's — managers only.",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢wheniwork_list_annotations(start_date, end_date, no_time_off)
List schedule annotations — announcements, business-closed days and blackout dates when time off is not allowed. Defaults to today through one year out. When I Work: GET /2/annotations.
Input Schema
{
"type": "object",
"properties": {
"start_date": {
"description": "Start of the range (default the start of today). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"end_date": {
"description": "End of the range (default one year after start). Date-time, e.g. 2026-10-05T08:00:00-05:00 (When I Work's own examples also use RFC 2822, e.g. \"Mon, 05 Oct 2026 08:00:00 -0500\").",
"type": "string"
},
"no_time_off": {
"description": "Only annotations that block time off.",
"type": "boolean"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴wheniwork_create_shift(location_id, start_time, end_time, user_id, position_id, ...)
Create one shift on a schedule — assigned to a user, or open (user_id 0). Created as a draft unless published is true. Undo by editing it or unpublishing. When I Work: POST /2/shifts.
Input Schema
{
"type": "object",
"properties": {
"location_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The schedule (location) the shift belongs to id."
},
"start_time": {
"type": "string",
"description": "Shift start, date-time with offset, e.g. 2026-10-05T08:00:00-05:00."
},
"end_time": {
"type": "string",
"description": "Shift end, date-time with offset."
},
"user_id": {
"description": "The user to assign. 0 (or omitted on create) makes it an open shift.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"position_id": {
"description": "Position for the shift.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"site_id": {
"description": "Job site for the shift.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"break_time": {
"description": "Unpaid break length in hours, e.g. 0.5.",
"type": "number",
"minimum": 0
},
"notes": {
"description": "Shift notes shown to the employee.",
"type": "string"
},
"color": {
"description": "Hex colour without #, e.g. cc0000.",
"type": "string",
"pattern": "^[0-9a-fA-F]{3,6}$"
},
"published": {
"description": "Publish it immediately (default: draft).",
"type": "boolean"
},
"is_shared": {
"description": "For an open shift: a shared open shift.",
"type": "boolean"
}
},
"required": [
"location_id",
"start_time",
"end_time"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴wheniwork_update_shift(shift_id, location_id, start_time, end_time, user_id, ...)
Change a shift — reassign it, move it, change position or notes. When I Work requires start_time, end_time and location_id on every update, so fetch the shift first and pass them back. This tool never sends a breaks array; When I Work documents that breaks omitted from an update's breaks list are removed, so re-check the shift's breaks afterwards. When I Work: PUT /2/shifts/{id}.
Input Schema
{
"type": "object",
"properties": {
"shift_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The shift id."
},
"location_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The schedule (location) id."
},
"start_time": {
"type": "string",
"description": "Shift start (required by the API even if unchanged)."
},
"end_time": {
"type": "string",
"description": "Shift end (required by the API even if unchanged)."
},
"user_id": {
"description": "The user to assign. 0 (or omitted on create) makes it an open shift.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"position_id": {
"description": "Position for the shift.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"site_id": {
"description": "Job site for the shift.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"break_time": {
"description": "Unpaid break length in hours, e.g. 0.5.",
"type": "number",
"minimum": 0
},
"notes": {
"description": "Shift notes shown to the employee.",
"type": "string"
},
"color": {
"description": "Hex colour without #, e.g. cc0000.",
"type": "string",
"pattern": "^[0-9a-fA-F]{3,6}$"
},
"published": {
"description": "Publish it immediately (default: draft).",
"type": "boolean"
},
"is_shared": {
"description": "For an open shift: a shared open shift.",
"type": "boolean"
}
},
"required": [
"shift_id",
"location_id",
"start_time",
"end_time"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴wheniwork_publish_shifts(ids)
Publish draft shifts so employees can see them. Publishing does not itself send notifications. Undo with wheniwork_unpublish_shifts. When I Work: POST /2/shifts/publish.
Input Schema
{
"type": "object",
"properties": {
"ids": {
"minItems": 1,
"maxItems": 1000,
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"description": "The shift ids to publish."
}
},
"required": [
"ids"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴wheniwork_unpublish_shifts(ids)
Return published shifts to draft, hiding them from employees. Undo with wheniwork_publish_shifts. When I Work: POST /2/shifts/unpublish.
Input Schema
{
"type": "object",
"properties": {
"ids": {
"minItems": 1,
"maxItems": 1000,
"type": "array",
"items": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"description": "The shift ids to unpublish."
}
},
"required": [
"ids"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴wheniwork_create_time_off_request(start_time, end_time, user_id, type_id, paid, ...)
Create a time-off request for a user (default the calling user). It starts pending; cancel it with wheniwork_update_time_off_request (status 1). Get type ids from wheniwork_list_time_off_types. When I Work: POST /2/requests.
Input Schema
{
"type": "object",
"properties": {
"start_time": {
"type": "string",
"description": "Start of the time off, full date-time."
},
"end_time": {
"type": "string",
"description": "End of the time off, full date-time."
},
"user_id": {
"description": "Who is taking time off (default the calling user).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"type_id": {
"description": "Time-off type id (Personal, Sick, Holiday...).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"paid": {
"description": "Whether it is paid time off.",
"type": "boolean"
},
"hours": {
"description": "Hours of paid time off to use.",
"type": "number",
"minimum": 0
}
},
"required": [
"start_time",
"end_time"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴wheniwork_update_time_off_request(request_id, status, start_time, end_time, hours)
Change a time-off request: set its status (0 pending, 1 canceled, 2 accepted/approved, 3 expired, 4 denied) and/or its dates or hours. Reversible — set the status back. start_time and end_time must be given together. When I Work: PUT /2/requests/{request_id}.
Input Schema
{
"type": "object",
"properties": {
"request_id": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The time-off request id."
},
"status": {
"description": "New status.",
"type": "integer",
"minimum": 0,
"maximum": 4
},
"start_time": {
"description": "New start, full date-time (give with end_time).",
"type": "string"
},
"end_time": {
"description": "New end, full date-time (give with start_time).",
"type": "string"
},
"hours": {
"description": "Hours of paid time off to use.",
"type": "number",
"minimum": 0
}
},
"required": [
"request_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Community
Evidence
Recent observations
verifiedversion not recorded21 tools