Xero MCP Server

Instructions

Implementation Reference

• src/handlers/list-xero-report-balance-sheet.handler.ts:37-62 (handler)

  Main handler function listXeroReportBalanceSheet that orchestrates fetching the balance sheet report from Xero, handling errors, and returning structured response.

  export async function listXeroReportBalanceSheet(params: ListReportBalanceSheetParams): Promise<XeroClientResponse<ReportWithRow>> {
      try {
          const balanceSheet = await getReportBalanceSheet(params);
  
          if (!balanceSheet) {
              return {
                  result: null,
                  isError: true,
                  error: "Failed to fetch balance sheet data from Xero.",
              };
          }
  
          return {
              result: balanceSheet,
              isError: false,
              error: null,
          };
      }
      catch (error) {
          return {
              result: null,
              isError: true,
              error: formatError(error),
          };
      }
  };

• src/handlers/list-xero-report-balance-sheet.handler.ts:10-35 (handler)

  Helper function within the handler file that performs the actual Xero API call to retrieve the balance sheet report.

  async function getReportBalanceSheet(params: ListReportBalanceSheetParams): Promise<ReportWithRow | null> {
      const {
          date,
          periods,
          timeframe,
          trackingOptionID1,
          trackingOptionID2,
          standardLayout,
          paymentsOnly,
      } = params;
  
      await xeroClient.authenticate();
  
      const response = await xeroClient.accountingApi.getReportBalanceSheet(
          xeroClient.tenantId,
          date || undefined,
          periods || undefined,
          timeframe || undefined,
          trackingOptionID1 || undefined,
          trackingOptionID2 || undefined,
          standardLayout ?? undefined,
          paymentsOnly ?? undefined,
          getClientHeaders(),
      );
      return response.body.reports?.[0] ?? null;
  }

• src/tools/list/list-report-balance-sheet.tool.ts:6-48 (registration)

  Creates and exports the tool named 'list-report-balance-sheet' using CreateXeroTool, including input schema (Zod), description, and execution logic that calls the handler and formats response.

  const ListReportBalanceSheetTool = CreateXeroTool(
    "list-report-balance-sheet",
    "List the Balance Sheet report from Xero.",
    {
      date: z.string().optional().describe("Optional date in YYYY-MM-DD format"),
      periods: z.number().optional().describe("Optional number of periods to compare"),
      timeframe: z.enum(["MONTH", "QUARTER", "YEAR"]).optional().describe("Optional timeframe for the report (MONTH, QUARTER, YEAR)"),
      trackingOptionID1: z.string().optional().describe("Optional tracking option ID 1"),
      trackingOptionID2: z.string().optional().describe("Optional tracking option ID 2"),
      standardLayout: z.boolean().optional().describe("Optional flag to use standard layout"),
      paymentsOnly: z.boolean().optional().describe("Optional flag to include only accounts with payments"),
    },
    async (args: ListReportBalanceSheetParams) => {
      const response = await listXeroReportBalanceSheet(args);
  
      // Check if the response contains an error
      if (response.error !== null) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error listing balance sheet report: ${response.error}`,
            },
          ],
        };
      }
  
      const balanceSheetReport = response.result;
  
      return {
        content: [
          {
            type: "text" as const,
            text: `Balance sheet Report: ${balanceSheetReport?.reportName ?? "Unnamed"}`,
          },
          {
            type: "text" as const,
            text: JSON.stringify(balanceSheetReport.rows, null, 2),
          },
        ],
      };
    }
  );

• src/types/list-report-balance-sheet-params.ts:4-12 (schema)

  TypeScript interface defining the input parameters for the list-report-balance-sheet tool.

  export interface ListReportBalanceSheetParams {
    date?: string;
    periods?: number;
    timeframe?: timeframeType;
    trackingOptionID1?: string;
    trackingOptionID2?: string;
    standardLayout?: boolean;
    paymentsOnly?: boolean;
  }

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

  Registers ListReportBalanceSheetTool in the ListTools array for inclusion in the tools list.

  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
  ];