Xero

Open Settings → Integrations and click Connecton the Xero card. You'll be redirected to Xero's login page, then to a consent screen showing the read scopes ShopMCP requests by default:

• accounting.contacts.read — customers and suppliers (the Contacts surface).
• accounting.settings.read — chart of accounts, items, tax rates, tracking categories, organisation profile, branding themes, currencies.
• accounting.attachments.read — file attachment metadata on invoices, bills, and other entities.
• accounting.invoices.read — invoices, credit notes, quotes (the sales / purchases transactional surface).
• accounting.payments.read — payments applied against invoices and credit notes.
• accounting.banktransactions.read — bank transactions, batch payments, prepayments, overpayments (the bank-feed-side ledger).
• accounting.manualjournals.read — accountant manual journals (separate from the daily-ledger /Journals endpoint).
• accounting.reports.aged.read — aged receivables / payables.
• accounting.reports.balancesheet.read — balance sheet report.
• accounting.reports.profitandloss.read — P&L report.
• accounting.reports.trialbalance.read — trial balance report.
• offline_access — required to receive a refresh token. Without it the access token would expire after 30 minutes with no recovery path.

On Xero's consent screen you'll see a tenant picker listing every organisation your Xero account can access — your own accounts, plus any organisations you've been invited to (common for accountants and agencies). Tick one or many.

When you approve, ShopMCP exchanges the code for tokens, calls GET https://api.xero.com/connections to enumerate the granted tenants, and creates one connection row per tenant. The first becomes primary; subsequent ones are non-primary and addressable via the store argument when the LLM has multiple connected.

By default, only read tools are registered — list invoices, pull reports, fetch bank transactions, etc. To allow the LLM to create invoices, apply payments, post manual journals, create contacts, or create bank transactions, flip the Allow writes toggle on the Xero card in the settings page.

The toggle does two things at once: it enables the per-workspace write flag and requires that your existing OAuth grant carry write scopes. If the original consent was read-only (the default), the settings page surfaces a Re-authorize for writesbanner — clicking it sends you back through Xero's consent flow with the additional write scopes:

• accounting.invoices — create / update invoices, credit notes, quotes (DRAFT / SUBMITTED — Xero rejects edits to AUTHORISED invoices).
• accounting.payments — apply payments against invoices and credit notes.
• accounting.banktransactions — create receive / spend / transfer / prepayment / overpayment lines directly against bank accounts.
• accounting.manualjournals — post manual journals (DRAFT or POSTED). Journal lines must net to zero.
• accounting.contacts — create / update contacts, archive contacts.
• accounting.attachments — upload binary attachments (deferred tooling — metadata read covered by the read-only attachments scope above).
• accounting.settings — write to settings-shaped resources (chart of accounts, tracking categories) when needed by tool-set.

The Xero card now shows Connectedwith the organisation name, and the connection list lets you label, set primary, and disconnect each tenant individually. Now go ask your LLM whatever you'd normally open Xero for — the prompts below are a starting point grouped by common workflows.

• What's our total AR aged 60+ days right now?
• Show me the top 25 customers by outstanding AR balance with their aging buckets.
• Which customers owe us more than $500 over 30 days, and when did we last email them? (also requires Klaviyo connected)
• Aged payables on this supplier — what's overdue?
• Find every authorised invoice past its due date, grouped by contact, sorted by amount.

• Run our P&L for Q1 with a comparison to Q1 last year.
• Profit and loss by tracking category — break it down by “Department”.
• Balance sheet as of last month-end with month-on-month comparison columns.
• Trial balance as of today on a cash basis.
• Executive summary for last month — cash, debtors, creditors, key ratios.

• Reconcile last week's Stripe payouts against my Xero bank feed and flag any mismatches. (requires Stripe connected)
• Find every Shopify order from last month that doesn't have a matching Xero invoice. (requires Shopify connected)
• Show me unreconciled bank transactions over $1,000 in our main account.
• Run my month-end close prep — stale invoices, draft journals, unallocated cash, prior-period adjustments.

• List every invoice over $5,000 in DRAFT status.
• Find this customer by email and pull their last 12 months of invoices.
• Show me the audit history on invoice INV-1234 — who edited it, when, and what changed?
• How many active customers do we have with non-zero AR?

The following prompts only work when Allow writes is toggled on and your OAuth grant includes write scopes (use the Re-authorize for writes banner if you originally connected with read-only consent).

• Create a draft invoice for Acme Pty Ltd for $1,200 + GST against account code 200, due in 14 days.
• Apply a $500 payment from our Stripe-clearing account against invoice INV-1234.
• Post a manual journal for the year-end accrual — $10,000 to 660 (Accrued expenses) credit, $10,000 to 400 (Wages) debit.
• Create a new contact: “Beta Holdings”, AccountNumber C-2042, customer + supplier, email finance@beta.example.
• Mark this credit note as allocated against invoice INV-1235 for the full remaining balance.

When you've connected 2+ Xero organisations to the same workspace, ShopMCP auto-injects a store argument into every Xero tool. The LLM picks a tenant by name (organisation name), label (anything you set in Settings), or tenant ID. Omit the argument to fall back to the primary organisation.

• What's our P&L this month for the AU subsidiary?
• Compare Q1 revenue across all our connected Xero organisations.

The Xero account you authorise needs at least Standard user access on every organisation you want to expose. Adviseraccess is recommended if you plan to enable write tools (it covers manual journals and bank reconciliation which Standard users can't edit). The OAuth grant also enforces the merchant's own role — flipping Allow writeson doesn't bypass Xero's permission model.

• Two uncertified apps per organisation.Xero caps each org to two connections from uncertified apps. ShopMCP is currently uncertified — cert is in progress. If your org already has Stripe / Receipt Bank / similar third-party apps connected, Xero may show “Uncertified app connection limit reached” on the consent screen for that org. Disconnect another uncertified app from My Xero → Connected apps to free a slot, or pick a different organisation.
• The daily-ledger view requires Advanced tier. Two of our tools (xero_list_journals + xero_get_journal) hit Xero's /Journalsendpoint, which is gated behind Xero's Advanced developer plan tier. On Starter or Core they'll surface a clear “requires Advanced tier” message instead of a generic 403. Every other Xero tool (invoices, reports, contacts, payments, manual journals, bank txns, attachments) is on the standard surface and works on every plan tier.

• “Uncertified app connection limit reached” — your Xero org already has 2 uncertified apps connected. Either disconnect one from My Xero → Connected apps, or pick a different organisation. ShopMCP's app certification is in progress; once it lands the cap doesn't apply to us.
• “More permission required”on an organisation in the consent dropdown — your Xero user role on that org doesn't include Accounting access. Ask the org owner to upgrade your role to Standard or Adviser, then retry.
• “No organisations were granted”— the Xero account you authorised had no organisations selected on the consent screen, or you're a Practice user with no orgs of your own. Re-run the connect flow and pick at least one organisation.
• “Re-authorize for writes” banner stays after re-OAuth— Xero's consent screen needs you to explicitly re-tick the write scopes. If you unticked them by mistake, click the banner again and confirm the new scopes are checked.
• 403 errors on write tools— your Xero role on the organisation doesn't allow that action. Manual journals require Adviser, for instance. Granting the OAuth scope doesn't bypass the user-role check.
• “Requires Advanced tier” on journals tools — the ShopMCP developer app is on Starter or Core; /Journals is gated behind Advanced (request-access only). Operator must upgrade. Other tools still work normally.
• Hitting 429 rate limits — Xero caps each tenant at 60 requests / minute and 5,000 / day. Long-running playbooks like AR aging fan-outs walk contacts sequentially; ask your LLM to narrow the customer list to top 10 if the run is slow.
• Refresh token revoked — Xero invalidates refresh tokens after 60 days idle, on user-initiated revoke (My Xero → Connected apps), or after a password reset. Reconnect from Settings → Xero — your label, primary toggle, and connection ID are preserved.