xero-mcp-enhanced

An enhanced Model Context Protocol (MCP) server for Xero, forked and significantly improved from the official Xero MCP server.

Point Claude Desktop (or any MCP-compatible client) at this server to interact with your Xero organisation using natural language.

---

What's improved over the official server

Area	Change
Auth scopes	Scopes are now configurable via XERO_SCOPES. The hardcoded scopes in the original broke apps created after 2 March 2026 when Xero introduced granular scope requirements.
Token refresh	Custom-connection tokens are now cached and only refreshed when they're within 60 seconds of expiry — instead of making an extra HTTP round-trip on every single API call.
Bearer token warnings	If XERO_CLIENT_BEARER_TOKEN is expired (or about to expire), a clear warning is logged rather than a cryptic 401.
Error messages	Xero validation errors, Elements[].ValidationErrors, and nested objects are now properly formatted instead of returning [object Object].
Bank transactions	list-bank-transactions now accepts contactId, fromDate, and toDate filters; page size increased to 100. update-bank-transaction now accepts lineAmountTypes (EXCLUSIVE / INCLUSIVE / NOTAX).
New tools	See table below.

---

New tools

Tool	Description
list-bank-transactions-by-contact	Fetch all transactions for a contact across a date range in one call (auto-paginating).
fix-gst-for-contact	Bulk-update tax type on all bank transaction line items for a contact in a date range. Skips DELETED/VOIDED transactions and those already on the target tax type. Note: transactions reconciled with a bank statement cannot be edited via the Xero API — unreconcile them in the Xero UI first.
list-bank-transfers	List transfers between bank accounts, with optional date range filter.
create-bank-transfer	Transfer funds between two Xero bank accounts.
list-repeating-invoices	List all recurring invoice templates (schedule, contact, amount, status).
list-currencies	List currencies enabled in the organisation.
get-contact	Get full contact details by ID (addresses, phones, balances, tax settings, deep link).
list-prepayments	List prepayments (advance payments), optionally filtered by contact.
list-overpayments	List overpayments (excess payments), optionally filtered by contact.

---

Prerequisites

• Node.js 18+
• A Xero account with either:
  • A Custom Connection app (recommended for persistent use), or
  • A manual Bearer token (expires after 30 minutes — useful for testing)

Setting up a Custom Connection app

1. Go to developer.xero.com/app/manage and create a new app
2. Select Custom Connection as the integration type
3. Under Scopes, select the scopes you need (see defaults below)
4. Copy the Client ID and Client Secret

---

Installation

Option A — run directly with npx (recommended for Claude Desktop)

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "github:danielreddd/xero-mcp-enhanced"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id",
        "XERO_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Option B — clone and build locally

git clone https://github.com/danielreddd/xero-mcp-enhanced.git
cd xero-mcp-enhanced
npm install
npm run build

Then in your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "xero": {
      "command": "node",
      "args": ["/absolute/path/to/xero-mcp-enhanced/dist/index.js"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id",
        "XERO_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

---

Configuration

Copy .env.example to .env and fill in your credentials, or pass environment variables directly in your MCP client config as shown above.

Environment variables

Variable	Required	Description
XERO_CLIENT_ID	Yes (unless using bearer token)	Client ID from your Xero app
XERO_CLIENT_SECRET	Yes (unless using bearer token)	Client secret from your Xero app
XERO_CLIENT_BEARER_TOKEN	Alternative to client ID/secret	Manual bearer token (expires in 30 min)
XERO_SCOPES	No	Space-separated OAuth scopes. See defaults below.

Default scopes

openid profile email accounting.transactions accounting.contacts accounting.settings accounting.reports.read accounting.attachments payroll.settings payroll.employees payroll.timesheets

For apps created before 2 March 2026 using the old broad scopes, you can override this to the shorter set:

accounting.transactions accounting.contacts accounting.settings accounting.reports.read payroll.settings payroll.employees payroll.timesheets

---

Complete tool list

List tools

• list-accounts — chart of accounts
• list-bank-transactions — with bankAccountId, contactId, fromDate, toDate filters
• list-bank-transactions-by-contact — all transactions for a contact (auto-paginated)
• list-bank-transfers — transfers between accounts
• list-contacts — search by name
• list-contact-groups
• list-credit-notes
• list-currencies
• list-invoices — filter by contact or invoice number
• list-items — products/services
• list-manual-journals
• list-organisation-details
• list-overpayments — filter by contact
• list-payments — filter by invoice, reference
• list-prepayments — filter by contact
• list-profit-and-loss
• list-quotes
• list-repeating-invoices
• list-report-balance-sheet
• list-tax-rates
• list-tracking-categories
• list-trial-balance
• list-aged-receivables-by-contact
• list-aged-payables-by-contact
• Payroll: list-payroll-employees, list-payroll-timesheets, list-payroll-employee-leave, list-payroll-leave-types, list-payroll-leave-periods, list-payroll-employee-leave-types, list-payroll-employee-leave-balances

Get tools

• get-contact — full contact details including addresses, phones, balances
• get-payroll-timesheet

Create tools

• create-bank-transaction
• create-bank-transfer
• create-contact
• create-credit-note
• create-invoice
• create-item
• create-manual-journal
• create-payment
• create-quote
• create-payroll-timesheet
• create-tracking-category / create-tracking-options

Update tools

• update-bank-transaction
• fix-gst-for-contact — bulk tax-type fix on bank transactions
• update-contact
• update-credit-note
• update-invoice
• update-item
• update-manual-journal
• update-quote
• update-tracking-category / update-tracking-options
• Payroll: approve-payroll-timesheet, revert-payroll-timesheet, update-payroll-timesheet-add-line, update-payroll-timesheet-update-line

Delete tools

• delete-payroll-timesheet

---

Using fix-gst-for-contact

This tool is designed for accountants who need to bulk-correct the tax type on bank transactions — for example, if a supplier was set up without GST and all their transactions need to be updated to INPUT2.

Recommended workflow:

1. Find the contact ID: use list-contacts and search by name
2. Preview transactions: use list-bank-transactions-by-contact with your date range
3. Check the tax rates: use list-tax-rates to confirm the correct tax type code
4. Run the fix: fix-gst-for-contact with the contactId, newTaxType, fromDate, toDate

Common Australian tax type codes:

Code	Description
OUTPUT2	GST on Income (15%)
INPUT2	GST on Expenses (15%)
EXEMPTOUTPUT	BAS Excluded on Sales
EXEMPTEXPENSES	BAS Excluded on Purchases
NONE	No Tax
ZERORATEDINPUT	Zero Rated Expenses

Note: This modifies reconciled transactions. Review the results and verify your bank reconciliation afterwards.

---

Security

• Credentials are read from environment variables — never hardcoded
• No credentials are logged or transmitted to any service other than Xero's own APIs
• Tokens are cached in-memory only and discarded when the process exits

---

License

MIT — see LICENSE