xero-mcp

A small, local Xero MCP server for looking up contacts and invoices from Codex—and making draft invoices when you actually mean draft invoices.

It runs on your Mac, talks to Xero over OAuth, and keeps its tokens in ~/.xero-mcp/tokens.json. No database, no hosted service, no mystery background process.

The guardrails

• It can find contacts, list invoices, and fetch a full invoice.

• It can create an ACCREC sales invoice as DRAFT.

• It can update an invoice only after checking that it is still DRAFT.

• It cannot approve, authorise, pay, send, email, void, or delete an invoice.

The point is to make the useful bit easy without giving an AI a route to finalise something in your books.

Related MCP server: Xero MCP Server

What you need

• macOS

• Node 20+ (Node 25 is fine)

• A Xero organisation you can access

• A Xero OAuth Web app

Set up the Xero app

1. Go to Xero Developer → My Apps and create a Web app using Standard auth code.

2. Add this exact OAuth redirect URI:

   http://localhost:3000/callback

   Xero allows localhost for this local flow, but not 127.0.0.1.

3. In the app's Configuration page, copy the Client ID and generate a Client Secret.

The app requests the smallest useful set of scopes:

offline_access accounting.contacts.read accounting.invoices accounting.settings.read

First run

git clone https://github.com/david-buck/xero-mcp.git
cd xero-mcp
cp .env.example .env
# Add the Client ID and Client Secret from Xero to .env
npm install
npm run auth

The auth command starts a short-lived listener on localhost:3000, opens the Xero approval page (and prints the URL if macOS does not open it), then saves the token locally. After that, it refreshes tokens automatically—no browser required unless access is revoked or refresh fails.

If you can access more than one Xero organisation, set XERO_TENANT_ID in .env before running auth. Otherwise it uses the first connected organisation.

Add it to Codex

Add this to ~/.codex/config.toml and replace the path with wherever you cloned the repo:

[mcp_servers.xero]
command = "node"
args = ["--env-file=/ABSOLUTE/PATH/TO/xero-mcp/.env", "/ABSOLUTE/PATH/TO/xero-mcp/src/index.js"]

Restart Codex. The server uses stdio, so it stays quiet unless there is something useful to report back through an MCP tool call.

Tools

To retrieve older invoices, call xero_list_invoices with { "page": 2, "limit": 20 }. Increment page until fewer than limit records return; an exact multiple may require a final empty page. Each call fetches one page and returns an array. Defaults remain page 1 and limit 20 (maximum 100).

For an exact number, use { "invoiceNumber": "INV-0123" }; surrounding whitespace is trimmed, and numbers containing commas are unsupported. You can combine invoiceNumber, contactId, and pagination. Pass a returned invoiceId to xero_get_invoice to fetch its full details.

Monetary invoice lines require a description, quantity, unit amount, and account code, with optional tax type. Description-only lines contain just description (for example, { "description": "Project notes" }) and optionally an existing lineItemId; they cannot contain quantity, unit amount, account, item, or tax fields. Monetary lines can also carry an existing Xero item code and, during updates, a line-item ID.

Unit prices support at most four decimal places; more precise values are rejected without rounding.

Dates use YYYY-MM-DD. New drafts accept lineAmountTypes: Exclusive, Inclusive, or NoTax, defaulting to Exclusive. Contact preferences are not applied automatically. Full invoice responses include the tax basis returned by Xero as lineAmountTypes; updates preserve the existing basis by omitting it from the request. Inputs are schema-validated, and Xero API errors are returned intact instead of being papered over.

New drafts also accept optional currencyCode, for example "USD"; surrounding whitespace is trimmed and letters are uppercased. Omitting it leaves Xero's organisation base-currency default. The currency must be enabled in the organisation; Xero validates this. Unit amounts are denominated in the chosen currency and this server does not convert them or set an exchange rate. You may use contact defaults to choose an explicit code; they are not applied automatically. Existing invoice currency cannot be changed through this server.

Updating lineItems replaces the invoice's complete line set. Preserve an existing line by sending its lineItemId; omit it only when intentionally creating a new line. This matches Xero's update semantics and prevents accidental loss of item linkage or lines that were not meant to change.

When drafting, start with the contact defaults, then use the account and tax-rate helpers if you need to choose or verify a code. If a line has no taxType, Xero uses the selected account's default tax rate.

A quick local check

npm run check
npm test
npm start

npm test runs offline behavioral tests with synthetic credentials and owned temporary token directories. It does not use your .env, saved tokens, or a live Xero account.

npm start waits for MCP input. Hit Ctrl-C when you are done.

Keep the private bits private

.env and node_modules are ignored by Git. Tokens live outside the repository at ~/.xero-mcp/tokens.json with local-only file permissions. Do not commit your .env file or paste your Client Secret into an issue.