xero-mcp

# Xero MCP

Covers usage of the Xero MCP server, including authentication
(OAuth2 bearer tokens) and related operational notes.

For browser-driven automation of the Xero web UI (not via MCP), see the
separate [`xero-browser`](../xero-browser/SKILL.md) skill instead.

## Authentication

The Xero MCP server needs a valid bearer token
(`XERO_CLIENT_BEARER_TOKEN`) in its environment. Tokens last ~30 minutes
and must be refreshed via the `xero-oauth` helper script.

**Trigger to read [`references/authentication.md`](references/authentication.md):**

- Xero MCP tools return authentication/authorization errors
- Starting a Xero workflow and unsure if the token is current
- Token has expired (~30 minute lifetime)
- First-time setup, or after revoking and re-authorizing the Xero app

That reference covers the `xero-oauth` script, prerequisites (`.env`
credentials, Xero app registration), the refresh-vs-full-flow choice,
and which config files get updated.

## Searching for records

The MCP list-* tools paginate at 10 records per page. Absence on page
1 is **not** absence in Xero. Before concluding a record is missing,
search by ID directly or page exhaustively.

See [`references/searching-records.md`](references/searching-records.md)
for the rules around `list-manual-journals`, `list-invoices`,
`list-bank-transactions`, and `list-contacts`.

## Manual journals (create / update / void)

The schema descriptions for `create-manual-journal` and
`update-manual-journal` are misleading on at least two points:

- `lineAmountTypes: "NO_TAX"` is rejected by the Xero API (use the
  default — omit the field — which serialises as `NoTax`).
- `update-manual-journal` says "Only works on draft manual journals",
  but in practice mutates POSTED MJs (narration, date, lines, status).

This makes the **void-and-replace** pattern (create new POSTED MJ
referencing the old UUID, then update the old to `status: VOIDED`)
viable via MCP without touching the web UI.

The response strings from the write tools also render input params
verbatim and show line items as `[object Object]` — so always confirm
state with `list-manual-journals manualJournalId=<uuid>` after every
write before trusting it.

See [`references/manual-journals.md`](references/manual-journals.md)
for the full void-and-replace recipe, common error messages, and the
token-expiry coupling that bites multi-step MJ workflows.