create-invoice
Generate invoices in Xero accounting software by specifying contact details, line items, and invoice type. Returns a direct link to view the created invoice.
Instructions
Create an invoice in Xero. When an invoice is created, a deep link to the invoice in Xero is returned. This deep link can be used to view the invoice in Xero directly. This link should be displayed to the user.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | The ID of the contact to create the invoice for. Can be obtained from the list-contacts tool. | |
| lineItems | Yes | ||
| type | Yes | The type of invoice to create. ACCREC is for sales invoices, Accounts Receivable, or customer invoices. ACCPAY is for purchase invoices, Accounts Payable invoices, supplier invoices, or bills. If the type is not specified, the default is ACCREC. | |
| reference | No | A reference number for the invoice. | |
| date | No | The date the invoice was created (YYYY-MM-DD format). |
Implementation Reference
- Defines the 'create-invoice' MCP tool using CreateXeroTool helper. Includes Zod input schema, description, and the main handler function that calls createXeroInvoice, handles errors, generates a deep link to the invoice, and formats the response.const CreateInvoiceTool = CreateXeroTool( "create-invoice", "Create an invoice in Xero.\ When an invoice is created, a deep link to the invoice in Xero is returned. \ This deep link can be used to view the invoice in Xero directly. \ This link should be displayed to the user.", { contactId: z.string().describe("The ID of the contact to create the invoice for. \ Can be obtained from the list-contacts tool."), lineItems: z.array(lineItemSchema), type: z.enum(["ACCREC", "ACCPAY"]).describe("The type of invoice to create. \ ACCREC is for sales invoices, Accounts Receivable, or customer invoices. \ ACCPAY is for purchase invoices, Accounts Payable invoices, supplier invoices, or bills. \ If the type is not specified, the default is ACCREC."), reference: z.string().describe("A reference number for the invoice.").optional(), date: z.string().describe("The date the invoice was created (YYYY-MM-DD format).").optional(), }, async ({ contactId, lineItems, type, reference, date }) => { const xeroInvoiceType = type === "ACCREC" ? Invoice.TypeEnum.ACCREC : Invoice.TypeEnum.ACCPAY; const result = await createXeroInvoice(contactId, lineItems, xeroInvoiceType, reference, date); if (result.isError) { return { content: [ { type: "text" as const, text: `Error creating invoice: ${result.error}`, }, ], }; } const invoice = result.result; const deepLink = invoice.invoiceID ? await getDeepLink( invoice.type === Invoice.TypeEnum.ACCREC ? DeepLinkType.INVOICE : DeepLinkType.BILL, invoice.invoiceID, ) : null; return { content: [ { type: "text" as const, text: [ "Invoice created successfully:", `ID: ${invoice?.invoiceID}`, `Contact: ${invoice?.contact?.name}`, `Type: ${invoice?.type}`, `Date: ${invoice?.date}`, `Total: ${invoice?.total}`, `Status: ${invoice?.status}`, deepLink ? `Link to view: ${deepLink}` : null, ] .filter(Boolean) .join("\n"), }, ], }; }, ); export default CreateInvoiceTool;
- Zod schemas for line item tracking and line items used in the create-invoice tool input validation.const trackingSchema = z.object({ name: z.string().describe("The name of the tracking category. Can be obtained from the list-tracking-categories tool"), option: z.string().describe("The name of the tracking option. Can be obtained from the list-tracking-categories tool"), trackingCategoryID: z.string().describe("The ID of the tracking category. \ Can be obtained from the list-tracking-categories tool"), }); const lineItemSchema = z.object({ description: z.string().describe("The description of the line item"), quantity: z.number().describe("The quantity of the line item"), unitAmount: z.number().describe("The price per unit of the line item"), accountCode: z.string().describe("The account code of the line item - can be obtained from the list-accounts tool"), taxType: z.string().describe("The tax type of the line item - can be obtained from the list-tax-rates tool"), itemCode: z.string().describe("The item code of the line item - can be obtained from the list-items tool \ If the item is not listed, add without an item code and ask the user if they would like to add an item code.").optional(), tracking: z.array(trackingSchema).describe("Up to 2 tracking categories and options can be added to the line item. \ Can be obtained from the list-tracking-categories tool. \ Only use if prompted by the user.").optional(), });
- Core handler function that creates the invoice via Xero API. Called by the tool handler. Includes authentication, invoice construction, API call, and error handling.export async function createXeroInvoice( contactId: string, lineItems: InvoiceLineItem[], type: Invoice.TypeEnum = Invoice.TypeEnum.ACCREC, reference?: string, date?: string, ): Promise<XeroClientResponse<Invoice>> { try { const createdInvoice = await createInvoice( contactId, lineItems, type, reference, date, ); if (!createdInvoice) { throw new Error("Invoice creation failed."); } return { result: createdInvoice, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } }
- src/tools/tool-factory.ts:17-19 (registration)Registers all CreateTools (including create-invoice tool) with 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 CreateInvoiceTool for registration in tool-factory.export const CreateTools = [ CreateContactTool, CreateCreditNoteTool, CreateManualJournalTool, CreateInvoiceTool, CreateQuoteTool, CreatePaymentTool, CreateItemTool, CreateBankTransactionTool, CreatePayrollTimesheetTool, CreateTrackingCategoryTool, CreateTrackingOptionsTool ];