Xero
Every call is scoped to one Xero organisation. The active organisation tenant is bound on the connection and sent automatically on each request.
Operational order
- Organisation — confirm legal entity, base currency, and tax settings before AR/AP work.
- Chart of accounts — list accounts when you need account codes for journals, bank lines, or items.
- Contacts — customers and suppliers for invoices, credit notes, bills, and payments.
- Invoices / credit notes / purchase orders / receipts — core AR/AP documents.
- Payments and bank transactions — cash application and bank feed rows.
- Manual journals — adjusting entries outside source documents.
- Reports — P&L, balance sheet, aged receivables/payables, trial balance, and other read-only report endpoints.
- Payroll — employees, pay runs, payslips, timesheets when payroll scopes are granted.
- Files / assets / projects — supporting documents, fixed assets register, and project time when those products are enabled.
Reads
Omit id to page a collection (page, optional where, optional order). Pass id to fetch one row.
Writes
All write tools use the upsert pattern:
- Create — omit id and supply row fields or body_json.
- Update — pass id plus changed fields or a full body_json object.
Xero accepts create and update through the same POST collection endpoint; updates must include the resource id inside the payload.
Draft invoices, quotes, and credit notes accept field edits only while Status is DRAFT. Use xero_update_document_status to submit, authorise, void, or delete without editing line items. When updating draft documents, omit LineItems to preserve existing lines or include the full set — partial line-item lists replace the document lines.
Attachments and large files
- xero_list_attachments, xero_download_attachment, and xero_upload_attachment handle document files.
- Inline base64 uploads are capped at 1 MB. Use local_path with MCPBundles Desktop or file_url (including prior spillover download links) for larger PDFs and images up to 100 MB.
- Large attachment downloads and financial reports return presigned S3 download links instead of inline base64 or giant JSON.
Organisation scope cache
After connect, MCPBundles caches account codes, contact names, tax types, bank-account availability, and Xero deeplink base URLs on the credential. Responses may include an org_scope envelope with cache age. Pass refresh_org_scope=true on xero_get_report after chart-of-accounts or contact changes.
Reports
Use xero_get_report with a report name such as ProfitAndLoss, BalanceSheet, TrialBalance, AgedReceivablesByContact, or AgedPayablesByContact, plus date parameters when required.
Report responses are snapshot-cached per credential for the same upstream parameters. Reuse compact, max_rows, and section_contains to narrow the presentation locally without another Xero call. Use refresh=true only when the user explicitly wants a fresh upstream fetch. xero_list_snapshots shows stored report snapshots for the connection.
MCP App panel
The Xero dashboard opens with xero_open_app or on the first panel-driving tool call. Single invoice, quote, and credit-note reads render a document card; financial reports render a table view in the same panel.
Multi-organisation users
When a user connects more than one Xero organisation, each organisation should be a separate connection. Use the connections listing tool to see authorised tenants and names.
Pagination and filters
- Default page size is 100 rows; walk page until a page returns fewer rows.
- where uses Xero's OData-like filter syntax on supported collections.
- Some collections support include_archived or summary_only.
