# When I Work MCP by usefulapi

> When I Work MCP by usefulapi is an MCP server. Check shifts, time clock entries, time-off requests, swaps and availability, and manage shifts. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Website:** https://usefulapi.io/when-i-work/
- **Repository:** https://github.com/m190/usefulapi-mcp/tree/HEAD/servers/when-i-work
- **MCP Registry name:** io.usefulapi/when-i-work
- **Listing updated:** 2026-11-13

## About

Check shifts, time clock entries, time-off requests, swaps and availability, and manage shifts.

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http when-i-work https://when-i-work.usefulapi.io/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://when-i-work.usefulapi.io/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "when-i-work": {
      "url": "https://when-i-work.usefulapi.io/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "when-i-work": {
      "type": "http",
      "url": "https://when-i-work.usefulapi.io/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "when-i-work": {
      "serverUrl": "https://when-i-work.usefulapi.io/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "when-i-work": {
      "type": "http",
      "url": "https://when-i-work.usefulapi.io/mcp"
    }
  }
}
```

## Tools

- `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.
- `wheniwork_list_users`: 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.
- `wheniwork_get_user`: Fetch one user by id — name, email, role, positions, schedules, wage. When I Work: GET /2/users/{id}.
- `wheniwork_list_locations`: 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.
- `wheniwork_list_positions`: List the positions (job roles such as Cashier or Dishwasher) in the account. When I Work: GET /2/positions.
- `wheniwork_list_shifts`: 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.
- `wheniwork_get_shift`: Fetch one shift by id, including its breaks and publish state. When I Work: GET /2/shifts/{id}.
- `wheniwork_list_eligible_users_for_shift`: 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.
- `wheniwork_list_times`: 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.
- `wheniwork_list_time_off_requests`: 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.
- `wheniwork_get_time_off_request`: Fetch one time-off request by id, with its message thread and users. When I Work: GET /2/requests/{request_id}.
- `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.
- `wheniwork_list_shift_swaps`: 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.
- `wheniwork_list_availability`: 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.
- `wheniwork_list_annotations`: 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.
- `wheniwork_create_shift`: 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.
- `wheniwork_update_shift`: 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}.
- `wheniwork_publish_shifts`: 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.
- `wheniwork_unpublish_shifts`: Return published shifts to draft, hiding them from employees. Undo with wheniwork_publish_shifts. When I Work: POST /2/shifts/unpublish.
- `wheniwork_create_time_off_request`: 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.
- `wheniwork_update_time_off_request`: 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}.

## FAQ

### How do I add When I Work MCP by usefulapi to Claude Code?

Run this command in your terminal: claude mcp add --transport http when-i-work https://when-i-work.usefulapi.io/mcp

---
Source: https://ai-powered.com/mcp/when-i-work-mcp-by-usefulapi
