Xero MCP Server

Instructions

Implementation Reference

• src/tools/list/list-tax-rates.tool.ts:4-59 (handler)

  Main handler implementation for the 'list-tax-rates' tool. Creates the tool using CreateXeroTool with empty input schema and formats the tax rates into a detailed text response.
  const ListTaxRatesTool = CreateXeroTool( "list-tax-rates", "Lists all tax rates in Xero. Use this tool to get the tax rates to be used when creating invoices in Xero", {}, async () => { const response = await listXeroTaxRates(); if (response.error !== null) { return { content: [ { type: "text" as const, text: `Error listing tax rates: ${response.error}`, }, ], }; } const taxRates = response.result; return { content: [ { type: "text" as const, text: `Found ${taxRates?.length || 0} tax rates:`, }, ...(taxRates?.map((taxRate) => ({ type: "text" as const, text: [ `Tax Rate: ${taxRate.name || "Unnamed"}`, `Tax Type: ${taxRate.taxType || "No tax type"}`, `Status: ${taxRate.status || "Unknown status"}`, `Display Tax Rate: ${taxRate.displayTaxRate || "0.0000"}%`, `Effective Rate: ${taxRate.effectiveRate || "0.0000"}%`, taxRate.taxComponents?.length ? `Tax Components:\n${taxRate.taxComponents .map( (comp) => ` - ${comp.name}: ${comp.rate}%${comp.isCompound ? " (Compound)" : ""}${comp.isNonRecoverable ? " (Non-recoverable)" : ""}`, ) .join("\n")}` : null, `Can Apply To:${[ taxRate.canApplyToAssets ? " Assets" : "", taxRate.canApplyToEquity ? " Equity" : "", taxRate.canApplyToExpenses ? " Expenses" : "", taxRate.canApplyToLiabilities ? " Liabilities" : "", taxRate.canApplyToRevenue ? " Revenue" : "", ].join("")}`, ] .filter(Boolean) .join("\n"), })) || []), ], }; }, );
• src/handlers/list-xero-tax-rates.handler.ts:22-40 (handler)

  Core handler function that performs the actual API call to Xero to list tax rates, handles errors, and returns structured response.
  export async function listXeroTaxRates(): Promise< XeroClientResponse<TaxRate[]> > { try { const taxRates = await getTaxRates(); return { result: taxRates, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } }
• src/tools/list/index.ts:27-40 (registration)

  Imports the ListTaxRatesTool and includes it in the exported ListTools array for grouping list-related tools.
  import ListTaxRatesTool from "./list-tax-rates.tool.js"; import ListTrackingCategoriesTool from "./list-tracking-categories.tool.js"; import ListTrialBalanceTool from "./list-trial-balance.tool.js"; import ListContactGroupsTool from "./list-contact-groups.tool.js"; export const ListTools = [ ListAccountsTool, ListContactsTool, ListCreditNotesTool, ListInvoicesTool, ListItemsTool, ListManualJournalsTool, ListQuotesTool, ListTaxRatesTool,
• src/helpers/create-xero-tool.ts:5-17 (helper)

  Helper factory function used to standardize the creation of all Xero MCP tools, including schema and handler binding.
  export const CreateXeroTool = <Args extends ZodRawShapeCompat>( name: string, description: string, schema: Args, handler: ToolCallback<Args>, ): (() => ToolDefinition<ZodRawShapeCompat>) => () => ({ name: name, description: description, schema: schema, handler: handler, });
• src/handlers/list-xero-tax-rates.handler.ts:7-17 (helper)

  Internal helper function that handles Xero client authentication and API call to retrieve tax rates.
  async function getTaxRates(): Promise<TaxRate[]> { await xeroClient.authenticate(); const taxRates = await xeroClient.accountingApi.getTaxRates( xeroClient.tenantId, undefined, // where undefined, // order getClientHeaders(), ); return taxRates.body.taxRates ?? []; }