Maintenance status, and the gap between `main` and open community PRs

[aspiers]

Hi, and thanks for publishing this server. It's been very useful.

The last merge to main was on 2026-06-05, and there are now 77 open pull requests, many of them fixes for bugs reported here (validation errors being swallowed, [object Object] in output, update-bank-transaction failing with 400s, invalid manual journal lineAmountTypes, and so on). Could a maintainer say whether the project is still actively maintained, and whether there's a plan for working through the PR queue?

To make the question concrete, I tried to find out what it would take to get the fixes and features I needed out of the open PRs, and ended up building a combined branch. It shows how far main has fallen behind what the community has already written. It also shows the kind of review and integration work a maintainer would face, and would keep facing as new PRs arrive:

• Triage: 77 open PRs, 38 shortlisted for a UK bookkeeping use case, 28 merged, plus one closed PR (fix: render complete organisation details #231) whose author offered to reopen it.
• Duplicates: 7 groups of PRs doing the same thing (e.g. four separate [object Object] fixes, three P&L fixes, two attachment implementations that register the same tool name), each needing one PR picked.
• Review: 3 PRs failed review, Accept LineItemID for partial invoice line updates #295 and feat: add invoice attachment list and download tools #126 as written and feat(auth): add self-refreshing token-file auth mode #200 without a locking fix (details in my comments on each). Several others add tools that make consequential writes to live books with no confirmation step.
• Conflicts: about 15 of the shortlisted PRs conflict with each other, mostly in shared tool files. Two pairs only work together after extra changes (Enhance list-invoices with advanced filtering (Type, status, dates, amounts) #110 + feat: improve bulk document reads #289, fix: preserve 4dp precision for invoice unit amounts (#1Preserve 4dp precision for invoice unit amounts (fixes #157)57) #216 + feat: add invoice currency code #296).
• Dependencies: xero-node is seven major versions behind (13 → 20). The upgrade (chore: upgrade xero-node to v20 #314) inserts new positional parameters, which breaks call sites in main and in three of the PRs until adjusted. tsc catches this, but the compiled JavaScript misbehaves without any error.
• Result: the combined build has 79 tools against 51 on main, and passes npm ci, tsc, lint and 92 unit tests.

The branch is on my fork. I'm not proposing it as an alternative to this repo or volunteering as an unofficial maintainer; it's a reference for what's ready to land. Since it exists, others may find it useful in the meantime:

• Branch (may occasionally be rebuilt and force-pushed; no maintenance commitment, so pin a tag if you need stability): https://github.com/aspiers/xero-mcp-server/tree/best-of-breed
• Snapshot tag to pin to: https://github.com/aspiers/xero-mcp-server/tree/best-of-breed-2026-09-23-2

Even a short note from the maintainers either way would help people decide whether to wait, contribute, or fork.

What's in the branch, how it was checked, and caveats

Base

• main + chore: upgrade xero-node to v20 #314 (xero-node 13 → 20.0.0). v20 includes the upstream fix that redacts request headers, including the bearer token, from SDK error objects. It also inserts new optional positional parameters before options in several API methods, so some PRs needed small compatibility fixes (see my comments on feat: add allocation tools (credit note / overpayment / prepayment) + list-overpayments/list-prepayments #187 and feat: add invoice currency code #296).

PRs included

Area	PRs
Error handling / security	#305, #214, #290
Auth	#200 (XERO_TOKEN_FILE self-refreshing token), plus my locking fixes described in #200 (comment)
Manual journals	#182, #181 (includes #180's code)
Bank transactions	#190, #153
Output formatting	#207, #231 (closed, reopen requested)
Reports	#186 (includes #198's fix)
Credit notes / allocations	#187, #194, #195, #291
Invoices / bills	#216, #221, #293, #294, #296, #308, #110 + #289 (combined so date filters and where are ANDed together)
Listing	#176 (pageSize on list tools)
New tools	#191 (linked transactions), #298 (general ledger journals), #145 (history & notes), #109 (attachments; without its unrelated xero-client.ts changes), #127 (invoice PDF / online URL)

Left out after review: #295 (a partial line update can delete the other lines; see my comment there), #126 (package rename and stale client rewrite; see my comment there), and duplicates superseded by the PRs above (#180, #197, #215, #313, #204, #178, #198, #161, #201). AU payroll, quotes and remote-hosting PRs are out of scope for my use, so I didn't evaluate them.

How it was checked

• An AI coding assistant reviewed each included PR's diff, and I read the results. The review looked at secret handling, network destinations, dependency and lockfile changes, and risks of corrupting accounting data. This is not a professional security audit.
• I exercised the read tools against a live UK organisation in token-file mode. That included the token file refreshing itself, with three server processes refreshing at the same moment. Bearer-token mode was only tested live with the v20 upgrade on its own.
• I have not exercised the write tools live.

Caveats

• Several included tools make consequential writes with no confirmation step:

  • feat: allow update-invoice to set an invoice's status #221 can approve, void or delete invoices
  • feat: add linked-transaction (billable expense) tools + surface Line Item ID #191 can delete or void linked transactions
  • feat: add History & Notes tools for 5 entities #145 adds history notes, which Xero doesn't let you edit or delete
  • feat: add delete-credit-note-allocation tool (+ show allocations in list-credit-notes) #194 deletes credit-note allocations
  • feat: allow date/reference updates on authorised credit notes #195 can re-date authorised credit notes

  Read the diffs before relying on them. A Xero lock date is a sensible safety net.

• Some tools need scopes the default setup doesn't request: accounting.attachments.read (Add attachment read functionality for invoices and manual journals #109) and accounting.journals.read (feat: add general ledger journal tools (list, get) #298).

• With XERO_TOKEN_FILE, set XERO_TENANT_ID. Otherwise writes go to the first connected organisation.

• package.json still says @xeroapi/xero-mcp-server. Please don't publish it under that name.

Using it

git clone -b best-of-breed https://github.com/aspiers/xero-mcp-server.git
cd xero-mcp-server
npm ci && npm run build

Then point your MCP client at node /path/to/xero-mcp-server/dist/index.js, with the same environment variables as the README. #200's README section covers the XERO_TOKEN_FILE mode.

[coderback]

Thanks for putting this together. One gap for multi-organisation users: the branch includes #200, whose XERO_TENANT_ID applies only in token-file mode. In bearer-token and Custom Connection mode the server still uses the first connected organisation, which is the #83 behaviour your caveats warn about.

#208 adds XERO_TENANT_ID to those two modes, and fails with a clear error rather than falling back if it doesn't match. I checked it against best-of-breed-2026-09-23-2: both commits apply with one README conflict (keep both sections), build and lint are clean, and the tests pass apart from #200's two 0600 permission tests, which also fail on the snapshot itself on Windows, where I ran them.

One thing to be aware of if you combine them: #200's token-file mode uses XERO_TENANT_ID as given, without checking it against /connections. A typo there still fails closed, because Xero rejects requests for an organisation the token isn't connected to, but with a less obvious error. Routing it through #208's selectTenantId would make the three modes behave the same, at the cost of one /connections call per authentication.

The risk isn't hypothetical: xorbitsai/xagent#2257, merged on 10 September, runs this server in bearer-token mode and lists first-organisation selection as an open issue.