Xero MCP Server

Instructions

Implementation Reference

• src/tools/list/list-trial-balance.tool.ts:5-48 (handler)

  Defines the MCP tool 'list-trial-balance' including Zod input schema, handler logic that calls core handler, and formats response as MCP content blocks.

  const ListTrialBalanceTool = CreateXeroTool(
    "list-trial-balance",
    "Lists trial balance in Xero. This provides a snapshot of the general ledger, showing debit and credit balances for each account.",
    {
      date: z.string().optional().describe("Optional date in YYYY-MM-DD format"),
      paymentsOnly: z.boolean().optional().describe("Optional flag to include only accounts with payments"),
    },
    async (args) => {
      const response = await listXeroTrialBalance(args?.date, args?.paymentsOnly);
      if (response.error !== null) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error listing trial balance: ${response.error}`,
            },
          ],
        };
      }
  
     const trialBalanceReport = response.result;
  
      return {
        content: [
          {
            type: "text" as const,
            text: `Trial Balance Report: ${trialBalanceReport?.reportName || "Unnamed"}`,
          },
          {
            type: "text" as const,
            text: `Date: ${trialBalanceReport?.reportDate || "Not specified"}`,
          },
          {
            type: "text" as const,
            text: `Updated At: ${trialBalanceReport?.updatedDateUTC ? trialBalanceReport.updatedDateUTC.toISOString() : "Unknown"}`,
          },
          {
            type: "text" as const,
            text: JSON.stringify(trialBalanceReport.rows, null, 2),
          },
        ],
      };
    },
  );

• src/handlers/list-xero-trial-balance.handler.ts:31-58 (handler)

  Core handler that fetches trial balance report from Xero API using xeroClient.accountingApi.getReportTrialBalance (via internal fetchTrialBalance).

  export async function listXeroTrialBalance(
    date?: string,
    paymentsOnly?: boolean,
  ): Promise<XeroClientResponse<ReportWithRow>> {
    try {
      const trialBalance = await fetchTrialBalance(date, paymentsOnly);
  
      if (!trialBalance) {
        return {
          result: null,
          isError: true,
          error: "Failed to fetch trial balance data from Xero.",
        };
      }
  
      return {
        result: trialBalance,
        isError: false,
        error: null,
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error),
      };
    }
  } 

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

  Registers the ListTrialBalanceTool in the ListTools array exported for higher-level registration.

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

• src/tools/tool-factory.ts:20-22 (registration)

  Final registration of all ListTools (including list-trial-balance) to the MCP server via server.tool() calls.

  ListTools.map((tool) => tool()).forEach((tool) =>
    server.tool(tool.name, tool.description, tool.schema, tool.handler),
  );