Xero MCP Server

Instructions

Implementation Reference

• src/handlers/get-xero-payroll-timesheet.handler.ts:22-40 (handler)

  Main handler function that retrieves a timesheet from Xero, handles errors, and returns a standardized response.
  export async function getXeroPayrollTimesheet(timesheetID: string): Promise< XeroClientResponse<Timesheet | null> > { try { const timesheet = await getTimesheet(timesheetID); return { result: timesheet, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } }
• src/handlers/get-xero-payroll-timesheet.handler.ts:7-17 (handler)

  Core helper function that authenticates the Xero client and fetches the timesheet data from the Xero Payroll NZ API.
  async function getTimesheet(timesheetID: string): Promise<Timesheet | null> { await xeroClient.authenticate(); // Call the Timesheet endpoint from the PayrollNZApi const timesheet = await xeroClient.payrollNZApi.getTimesheet( xeroClient.tenantId, timesheetID, ); return timesheet.body.timesheet ?? null; }
• src/tools/get/get-payroll-timesheet.tool.ts:8-61 (registration)

  Defines, registers, and exports the 'get-timesheet' tool using CreateXeroTool helper. Includes input schema, description, and a wrapper handler that formats the response as MCP content.
  const GetPayrollTimesheetTool = CreateXeroTool( "get-timesheet", `Retrieve a single payroll timesheet from Xero by its ID. This provides details such as the timesheet ID, employee ID, start and end dates, total hours, and the last updated date.`, { timesheetID: z.string().describe("The ID of the timesheet to retrieve."), }, async (params: { timesheetID: string }) => { const { timesheetID } = params; const response = await getXeroPayrollTimesheet(timesheetID); if (response.isError) { return { content: [ { type: "text" as const, text: `Error retrieving timesheet: ${response.error}`, }, ], }; } const timesheet = response.result; if (!timesheet) { return { content: [ { type: "text" as const, text: `No timesheet found with ID: ${timesheetID}`, }, ], }; } return { content: [ { type: "text" as const, text: [ `Timesheet ID: ${timesheet.timesheetID}`, `Employee ID: ${timesheet.employeeID}`, `Start Date: ${timesheet.startDate}`, `End Date: ${timesheet.endDate}`, `Total Hours: ${timesheet.totalHours}`, `Last Updated: ${timesheet.updatedDateUTC}`, ] .filter(Boolean) .join("\n"), }, ], }; }, );
• src/tools/get/get-payroll-timesheet.tool.ts:12-14 (schema)

  Zod schema for the tool's input parameters: timesheetID as string.
  { timesheetID: z.string().describe("The ID of the timesheet to retrieve."), },