list-session-recordings
Retrieve Microsoft Clarity session recordings by applying filters for date, URLs, devices, browsers, locations, user behavior, and performance metrics to analyze user interactions.
Instructions
List Microsoft Clarity session recordings based on specified filters. The filters allow you to narrow down the recordings by various criteria such as URLs, device types, browser, OS, country, city, and more. The date filter is required and must be in UTC ISO 8601 format.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filters | Yes | A set of filters that can be applied to the Microsoft Clarity to session recordings. This allows you to filter recordings based on various criteria such as URLs, device types, browser, OS, country, city, and more. The date filter is required and must be in UTC ISO 8601 format. | |
| sortBy | No | Sort option for session recordings. Default is SessionStart_DESC (newest first). | SessionStart_DESC |
| count | No | The number of sample session recordings to return. Default is 100. Maximum is 250. |
Implementation Reference
- src/tools.ts:44-65 (handler)Core handler function that executes the HTTP POST request to the Clarity API endpoint for listing session recordings based on date range, filters, sort options, and count.export async function listSessionRecordingsAsync( startDate: Date, endDate: Date, filters: FiltersType, sortBy: SortOptionsType, count: number ): Promise<any> { return await tryAsync(SESSION_RECORDINGS_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', ...(CLARITY_API_TOKEN ? { 'Authorization': `Bearer ${CLARITY_API_TOKEN}` } : {}) }, body: JSON.stringify({ sortBy: SortOptionsEnum[sortBy], start: startDate.toISOString(), end: endDate.toISOString(), filters: filters, count: count }) }); }
- src/index.ts:59-83 (registration)Tool registration in the MCP server using server.tool(), providing the tool name (SESSION_RECORDINGS_TOOL), description, input schema (ListRequest), metadata, and an inline wrapper handler that processes parameters and delegates to listSessionRecordingsAsync.// Register the session-recordings tool server.tool( SESSION_RECORDINGS_TOOL, /* Name */ SESSION_RECORDINGS_DESCRIPTION, /* Description */ ListRequest, /* Parameter Schema */ { /* Metadata & Annotations */ title: "List Session Recordings", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ filters, sortBy, count }) => { const now = new Date().toISOString(); // Calculate end as now, start as now - numOfDays const endDate = new Date(filters?.date?.end || now); const startDate = new Date(filters?.date?.start || now); if (!filters?.date?.start) { startDate.setDate(endDate.getDate() - 2); } return await listSessionRecordingsAsync(startDate, endDate, filters, sortBy, count); } );
- src/types.ts:104-108 (schema)Zod-based input schema definition for the list-session-recordings tool, specifying filters (complex object with many optional fields), sortBy, and count parameters.export const ListRequest = { filters: Filters, sortBy: SortOptions, count: SampleCount };
- src/constants.ts:14-14 (helper)Constant definition for the tool name used in registration and instructions.export const SESSION_RECORDINGS_TOOL = "list-session-recordings";
- src/constants.ts:19-19 (helper)Tool description constant used in registration.export const SESSION_RECORDINGS_DESCRIPTION = "List Microsoft Clarity session recordings based on specified filters. The filters allow you to narrow down the recordings by various criteria such as URLs, device types, browser, OS, country, city, and more. The date filter is required and must be in UTC ISO 8601 format.";