Xero MCP Server

Instructions

Implementation Reference

• src/handlers/list-aged-receivables-by-contact.handler.ts:27-56 (handler)

  Core handler function that invokes the Xero API call via the inner helper and handles errors, returning structured response.

  export async function listXeroAgedReceivablesByContact(
    contactId: string,
    reportDate?: string,
    invoicesFromDate?: string,
    invoicesToDate?: string
  ): Promise<XeroClientResponse<ReportWithRow>> {
    try {
      const agedReceivables = await listAgedReceivablesByContact(contactId, reportDate, invoicesFromDate, invoicesToDate);
  
      if (!agedReceivables) {
        return {
          result: null,
          isError: true,
          error: "Failed to get aged receivables by contact from Xero."
        };
      }
  
      return {
        result: agedReceivables,
        isError: false,
        error: null
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  }

• src/handlers/list-aged-receivables-by-contact.handler.ts:7-25 (helper)

  Low-level helper that performs authentication and direct API call to Xero's getReportAgedReceivablesByContact endpoint.

  async function listAgedReceivablesByContact(
    contactId: string,
    reportDate?: string,
    invoicesFromDate?: string,
    invoicesToDate?: string
  ): Promise<ReportWithRow | undefined> {
    await xeroClient.authenticate();
  
    const response = await xeroClient.accountingApi.getReportAgedReceivablesByContact(
      xeroClient.tenantId, // xeroTenantId
      contactId, // contactId
      reportDate, // date
      invoicesFromDate, // fromDate
      invoicesToDate, // toDate
      getClientHeaders()
    );
  
    return response.body.reports?.[0];
  }

• src/tools/list/list-aged-receivables-by-contact.tool.ts:10-18 (schema)

  Zod schema defining the input parameters for the MCP tool.

  {
    contactId: z.string(),
    reportDate: z.string().optional()
      .describe("Optional date to retrieve aged receivables in YYYY-MM-DD format. If none is provided, defaults to end of the current month."),
    invoicesFromDate: z.string().optional()
      .describe("Optional from date in YYYY-MM-DD format. If provided, will only show payable invoices after this date for the contact."),
    invoicesToDate: z.string().optional()
      .describe("Optional to date in YYYY-MM-DD format. If provided, will only show payable invoices before this date for the contact."),
  },

• src/tools/list/list-aged-receivables-by-contact.tool.ts:19-55 (handler)

  MCP tool execution handler that calls the core handler, processes the result, and formats output as MCP content blocks.

  async ({ contactId, reportDate, invoicesFromDate, invoicesToDate }) => {
    const response = await listXeroAgedReceivablesByContact(contactId, reportDate, invoicesFromDate, invoicesToDate);
    
    if (response.isError) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error listing aged receivables by contact: ${response.error}`,
          },
        ],
      };
    }
  
    const agedReceivablesReport = response.result;
    const filter = formatAgedReportFilter(invoicesFromDate, invoicesToDate);
  
    return {
      content: [
        {
          type: "text" as const,
          text: `Report Name: ${agedReceivablesReport.reportName || "Not specified"}`,
        },
        {
          type: "text" as const,
          text: `Report Date: ${agedReceivablesReport.reportDate || "Not specified"}`
        },
        {
          type: "text" as const,
          text: filter ?? "Showing all relevant invoices"
        },
        {
          type: "text" as const,
          text: JSON.stringify(agedReceivablesReport.rows, null, 2),
        }
      ],
    };

• src/tools/list/index.ts:32-58 (registration)

  Registration of the tool in the ListTools array, which is likely used to register all list tools with the MCP server.

  export const ListTools = [
    ListAccountsTool,
    ListContactsTool,
    ListCreditNotesTool,
    ListInvoicesTool,
    ListItemsTool,
    ListManualJournalsTool,
    ListQuotesTool,
    ListTaxRatesTool,
    ListTrialBalanceTool,
    ListPaymentsTool,
    ListProfitAndLossTool,
    ListBankTransactionsTool,
    ListPayrollEmployeesTool,
    ListReportBalanceSheetTool,
    ListOrganisationDetailsTool,
    ListPayrollEmployeeLeaveTool,
    ListPayrollLeavePeriodsToolTool,
    ListPayrollEmployeeLeaveTypesTool,
    ListPayrollEmployeeLeaveBalancesTool,
    ListPayrollLeaveTypesTool,
    ListAgedReceivablesByContact,
    ListAgedPayablesByContact,
    ListPayrollTimesheetsTool,
    ListContactGroupsTool,
    ListTrackingCategoriesTool
  ];