Xero MCP Server

This is a Model Context Protocol (MCP) server implementation for Xero. It provides a bridge between the MCP protocol and Xero's API, allowing for standardized access to Xero's accounting and business features.

Features

• Xero OAuth2 authentication with custom connections
• Contact management
• Chart of Accounts management
• Invoice creation and management
• MCP protocol compliance

Prerequisites

• Node.js (v18 or higher)
• npm or pnpm
• A Xero developer account with API credentials

Docs and Links

• Xero Public API Documentation
• Xero API Explorer
• Xero OpenAPI Specs
• Xero-Node Public API SDK Docs
• Developer Documentation

Setup

Create a Xero Account

If you don't already have a Xero account and organisation already, can create one by signing up here using the free trial.

We recommend using a Demo Company to start with because it comes with some pre-loaded sample data. Once you are logged in, switch to it by using the top left-hand dropdown and selecting "Demo Company". You can reset the data on a Demo Company, or change the country, at any time by using the top left-hand dropdown and navigating to My Xero.

NOTE: To use Payroll-specific queries, the region should be either NZ or UK.

Authentication

There are 2 modes of authentication supported in the Xero MCP server:

1. Custom Connections

This is a better choice for testing and development which allows you to specify client id and secrets for a specific organisation. It is also the recommended approach if you are integrating this into 3rd party MCP clients such as Claude Desktop.

Configuring your Xero Developer account

Set up a Custom Connection following these instructions: https://developer.xero.com/documentation/guides/oauth2/custom-connections/

Currently the following scopes are required for all sessions: scopes

Integrating the MCP server with Claude Desktop

To add the MCP server to Claude go to Settings > Developer > Edit config and add the following to your claude_desktop_config.json file:

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

NOTE: If you are using Node Version Manager "command": "npx" section change it to be the full path to the executable, ie: your_home_directory/.nvm/versions/node/v22.14.0/bin/npx on Mac / Linux or "your_home_directory\\.nvm\\versions\\node\\v22.14.0\\bin\\npx" on Windows

2. Bearer Token

This is a better choice if you are to support multiple Xero accounts at runtime and allow the MCP client to execute an auth flow (such as PKCE) as required. In this case, use the following configuration:

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

NOTE: The XERO_CLIENT_BEARER_TOKEN will take precedence over the XERO_CLIENT_ID if defined.

Required Scopes for Bearer Token

When obtaining a bearer token, you must request the appropriate scopes. The scopes you request should be:

Note: Some scopes are being deprecated in favour of more granular scopes. See the Xero OAuth 2.0 Scopes documentation for details on deprecation timelines.

accounting.transactions (Deprecated)
accounting.transactions.read (Deprecated)
accounting.invoices
accounting.invoices.read
accounting.attachments
accounting.attachments.read
accounting.payments
accounting.payments.read
accounting.banktransactions
accounting.banktransactions.read
accounting.manualjournals
accounting.manualjournals.read
accounting.reports.read (Deprecated)
accounting.reports.aged.read
accounting.reports.balancesheet.read
accounting.reports.profitandloss.read
accounting.reports.trialbalance.read
accounting.contacts 
accounting.settings 
files
files.read
payroll.settings 
payroll.employees 
payroll.timesheets

Available MCP Commands

• list-accounts: Retrieve a list of accounts
• list-attachments: Retrieve attachments for a supported Xero object
• list-contacts: Retrieve a list of contacts from Xero
• list-credit-notes: Retrieve a list of credit notes
• list-file-folders: Retrieve folders from Xero Files, including the Inbox folder metadata
• list-files: Retrieve files from Xero Files
• list-invoices: Retrieve a list of invoices
• list-items: Retrieve a list of items
• list-manual-journals: Retrieve a list of manual journals
• list-organisation-details: Retrieve details about an organisation
• list-profit-and-loss: Retrieve a profit and loss report
• list-quotes: Retrieve a list of quotes
• list-tax-rates: Retrieve a list of tax rates
• list-payments: Retrieve a list of payments
• list-trial-balance: Retrieve a trial balance report
• list-bank-transactions: Retrieve a list of bank account transactions
• list-payroll-employees: Retrieve a list of Payroll Employees
• list-report-balance-sheet: Retrieve a balance sheet report
• list-payroll-employee-leave: Retrieve a Payroll Employee's leave records
• list-payroll-employee-leave-balances: Retrieve a Payroll Employee's leave balances
• list-payroll-employee-leave-types: Retrieve a list of Payroll leave types
• list-payroll-leave-periods: Retrieve a list of a Payroll Employee's leave periods
• list-payroll-leave-types: Retrieve a list of all available leave types in Xero Payroll
• list-timesheets: Retrieve a list of Payroll Timesheets
• list-aged-receivables-by-contact: Retrieves aged receivables for a contact
• list-aged-payables-by-contact: Retrieves aged payables for a contact
• list-contact-groups: Retrieve a list of contact groups
• list-tracking-categories: Retrieve a list of tracking categories
• create-bank-transaction: Create a new bank transaction
• add-attachment: Upload an attachment to a supported Xero object
• associate-file: Associate a Xero Files document with a Xero object
• create-contact: Create a new contact
• create-credit-note: Create a new credit note
• create-file-folder: Create a folder in Xero Files
• create-invoice: Create a new invoice
• create-item: Create a new item
• create-manual-journal: Create a new manual journal
• create-payment: Create a new payment
• create-quote: Create a new quote
• create-payroll-timesheet: Create a new Payroll Timesheet
• create-tracking-category: Create a new tracking category
• create-tracking-option: Create a new tracking option
• upload-file: Upload a file to Xero Files. If no folder is specified the file appears in Archive in the Xero UI; direct Inbox uploads are not supported
• update-bank-transaction: Update an existing bank transaction
• approve-invoice: Approve an invoice or bill by setting it to AUTHORISED
• email-invoice: Send an approved invoice to the related contact by email
• approve-and-email-invoice: Approve an invoice and send it by email in one step
• update-contact: Update an existing contact
• update-file: Update a Xero Files document
• update-file-folder: Update a Xero Files folder
• update-invoice-fields: Update specific invoice or bill fields such as due date without sending line items
• update-invoice: Update an existing draft invoice
• update-item: Update an existing item
• update-manual-journal: Update an existing manual journal
• update-quote: Update an existing draft quote
• update-credit-note: Update an existing draft credit note
• update-tracking-category: Update an existing tracking category
• update-tracking-options: Update tracking options
• update-payroll-timesheet-line: Update a line on an existing Payroll Timesheet
• approve-payroll-timesheet: Approve a Payroll Timesheet
• revert-payroll-timesheet: Revert an approved Payroll Timesheet
• add-payroll-timesheet-line: Add new line on an existing Payroll Timesheet
• delete-file: Delete a Xero Files document
• delete-file-folder: Delete a Xero Files folder
• delete-payroll-timesheet: Delete an existing Payroll Timesheet
• remove-file-association: Remove an association between a Xero Files document and a Xero object
• get-attachment: Retrieve the contents of an accounting attachment
• get-file: Retrieve the contents of a Xero Files document
• get-payroll-timesheet: Retrieve an existing Payroll Timesheet

Files and Attachments Notes

• list-attachments, add-attachment, and get-attachment all work for both sales invoices (ACCREC) and bills (ACCPAY) by using objectType: Invoices.
• add-attachment and upload-file both accept base64 content or an absolute local filePath. If both filePath and fileContent are provided, filePath takes precedence.
• If contentType is omitted while using filePath, the server attempts to infer the MIME type from the file extension.
• add-attachment attaches a file to a specific Xero object, while upload-file stores a standalone document in Xero Files.
• get-attachment and get-file return base64 content and responses can be large.
• list-files can be filtered by folderId.
• upload-file works best with an explicit non-Inbox folderId for reliable placement. Prefer creating a named folder such as Invoices and uploading directly to it. If no folder is specified, files may land in Archive rather than Inbox in the Xero UI.
• update-file can rename a file and move it between folders.
• delete-file permanently deletes the file.
• list-file-folders returns the Inbox plus any custom folders.
• update-file-folder renames a folder only.
• delete-file-folder cannot delete the Inbox folder.

Contact Notes

• Xero contacts do expose Supplier and Customer flags, but Xero marks both as read-only.
• Supplier is automatically set by Xero once the contact has AP activity such as bills.
• Customer is automatically set by Xero once the contact has AR activity such as sales invoices.
• create-contact and update-contact do not accept writable supplier or customer fields because Xero will reject them.
• list-contacts, create-contact, and update-contact surface the current contact role in MCP responses when Xero returns it.

Invoice Workflow Notes

• list-invoices supports server-side statuses filtering, for example ["DRAFT"], so you can page only through draft invoices instead of all invoices.
• approve-invoice sets a DRAFT or SUBMITTED invoice or bill to AUTHORISED.
• email-invoice uses Xero's invoice email endpoint and requires the invoice to already be approved and the related contact to have an email address.
• approve-and-email-invoice approves a DRAFT or SUBMITTED invoice first, then emails it in the same MCP action.
• update-invoice-fields supports targeted top-level invoice changes such as dueDate, date, reference, contactId, expectedPaymentDate, and plannedPaymentDate without sending line items.
• update-invoice remains the draft-only tool for full invoice edits where line items are being changed.

For detailed API documentation, please refer to the MCP Protocol Specification.

For Developers

Installation

# Using npm
npm install

# Using pnpm
pnpm install

Run a build

# Using npm
npm run build

# Using pnpm
pnpm build

Integrating with Claude Desktop

To link your Xero MCP server in development to Claude Desktop go to Settings > Developer > Edit config and add the following to your claude_desktop_config.json file:

NOTE: For Windows ensure the args path escapes the \ between folders ie. "C:\\projects\xero-mcp-server\\dist\\index.js"

{
  "mcpServers": {
    "xero": {
      "command": "node",
      "args": ["insert-your-file-path-here/xero-mcp-server/dist/index.js"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

License

MIT

Security

Please do not commit your .env file or any sensitive credentials to version control (it is included in .gitignore as a safe default.)