Xero MCP Server

Instructions

Implementation Reference

• src/handlers/create-xero-bank-transaction.handler.ts:57-84 (handler)

  Core exported handler function `createXeroBankTransaction` that creates the bank transaction by calling internal API logic and handles errors.

  export async function createXeroBankTransaction(
    type: BankTransactionType,
    bankAccountId: string,
    contactId: string,
    lineItems: BankTransactionLineItem[],
    reference?: string,
    date?: string
  ): Promise<XeroClientResponse<BankTransaction>> {
    try {
      const createdTransaction = await createBankTransaction(type, bankAccountId, contactId, lineItems, reference, date);
    
      if (!createdTransaction) {
        throw new Error("Bank transaction creation failed.");
      }
  
      return {
        result: createdTransaction,
        isError: false,
        error: null
      };
    } catch (error) {
      return {
        result: null,
        isError: true,
        error: formatError(error)  
      };
    }
  }

• src/handlers/create-xero-bank-transaction.handler.ts:17-55 (handler)

  Internal helper function that constructs and sends the bank transaction to Xero API.

  async function createBankTransaction(
    type: BankTransactionType,
    bankAccountId: string,
    contactId: string,
    lineItems: BankTransactionLineItem[],
    reference?: string,
    date?: string
  ): Promise<BankTransaction | undefined> {
    await xeroClient.authenticate();
  
    const bankTransaction: BankTransaction = {
      type: BankTransaction.TypeEnum[type],
      bankAccount: {
        accountID: bankAccountId
      },
      contact: {
        contactID: contactId
      },
      lineItems: lineItems,
      date: date ?? new Date().toISOString().split("T")[0],
      reference: reference,
      status: BankTransaction.StatusEnum.AUTHORISED
    };
  
    const response = await xeroClient.accountingApi.createBankTransactions(
      xeroClient.tenantId, // xeroTenantId
      {
        bankTransactions: [bankTransaction]
      }, // bankTransactions
      true, // summarizeErrors
      undefined, // unitdp
      undefined, // idempotencyKey
      getClientHeaders()
    );
  
    const createdBankTransaction = response.body.bankTransactions?.[0];
  
    return createdBankTransaction;
  }

• src/tools/create/create-bank-transaction.tool.ts:6-29 (schema)

  Zod schema definition for tool inputs including line items and main parameters.

  const lineItemSchema = z.object({
    description: z.string(),
    quantity: z.number(),
    unitAmount: z.number(),
    accountCode: z.string(),
    taxType: z.string(),
  });
  
  const CreateBankTransactionTool = CreateXeroTool(
    "create-bank-transaction",
    `Create a bank transaction in Xero.
    When a bank transaction is created, a deep link to the bank transaction in Xero is returned.
    This deep link can be used to view the bank transaction in Xero directly.
    This link should be displayed to the user.`,
    {
      type: z.enum(["RECEIVE", "SPEND"]),
      bankAccountId: z.string(),
      contactId: z.string(),
      lineItems: z.array(lineItemSchema),
      reference: z.string().optional(),
      date: z.string()
        .optional()
        .describe("If no date is provided, the date will default to today's date")
    },

• src/tools/create/create-bank-transaction.tool.ts:30-66 (handler)

  Tool-specific handler that processes the core handler result, generates deep link, and formats MCP response.

  async ({ type, bankAccountId, contactId, lineItems, reference, date }) => {
    const result = await createXeroBankTransaction(type, bankAccountId, contactId, lineItems, reference, date);
  
    if (result.isError) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error creating bank transaction: ${result.error}`
          }
        ]
      };
    }
  
    const bankTransaction = result.result;
  
    const deepLink = bankTransaction.bankAccount.accountID && bankTransaction.bankTransactionID
      ? bankTransactionDeepLink(bankTransaction.bankAccount.accountID, bankTransaction.bankTransactionID)
      : null;
  
    return {
      content: [
        {
          type: "text" as const,
          text: [
            "Bank transaction successfully:",
            `ID: ${bankTransaction?.bankTransactionID}`,
            `Date: ${bankTransaction?.date}`,
            `Contact: ${bankTransaction?.contact?.name}`,
            `Total: ${bankTransaction?.total}`,
            `Status: ${bankTransaction?.status}`,
            deepLink ? `Link to view: ${deepLink}` : null
          ].filter(Boolean).join("\n"),
        },
      ],
    };
  }

• src/tools/tool-factory.ts:17-19 (registration)

  Registers the create-bank-transaction tool (via CreateTools) to the MCP server using server.tool()

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

• src/tools/create/index.ts:13-25 (registration)

  Exports array of create tools including CreateBankTransactionTool for registration in tool factory.

  export const CreateTools = [
    CreateContactTool,
    CreateCreditNoteTool,
    CreateManualJournalTool,
    CreateInvoiceTool,
    CreateQuoteTool,
    CreatePaymentTool,
    CreateItemTool,
    CreateBankTransactionTool,
    CreatePayrollTimesheetTool,
    CreateTrackingCategoryTool,
    CreateTrackingOptionsTool
  ];