Purpose

xero-mcp-server is a Model Context Protocol (MCP) server implementation for Xero. It provides a bridge between the MCP protocol and the Xero API, enabling MCP clients to access Xero's accounting and business functions in a standardized way. This server follows the MCP protocol specification; for an introduction to the protocol, see https://modelcontextprotocol.io/introduction。

Main Capabilities

According to the materials, this server provides the following capabilities:

Xero OAuth2 authentication, with support for Custom Connections
Contact management
Chart of Accounts management
Invoice creation and management
MCP protocol compliance

Environment Requirements

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

Preparation

If you do not yet have a Xero account and organization, you can create one by signing up for a free trial. It is recommended to start with the Demo Company, as it comes with some preloaded sample data. After logging in, you can switch by selecting "Demo Company" from the dropdown menu in the upper left corner. You can use the dropdown menu in the upper left corner at any time to go to My Xero to reset the Demo Company's data or change the country.

Note: To use Payroll-related queries, the region should be NZ or UK.

Authentication Methods

The Xero MCP server supports 2 authentication modes.

Custom Connections

This is a better choice for testing and development, allowing you to specify a client id and secret for a specific organization. It is also recommended if you want to integrate it into a third-party MCP client (such as Claude Desktop).

Set up a custom connection as instructed:https://developer.xero.com/documentation/guides/oauth2/custom-connections/

Custom connections require different scopes depending on when they were created. All scopes in the relevant list must be added to the custom connection:

Note: The MCP server will automatically try V1 scopes first and fall back to V2 if necessary.

These defaults can be overridden by setting the XERO_SCOPES environment variable to a space-separated list of scopes.

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

The XERO_SCOPES variable is optional. If omitted, the default scopes listed above will be used.

Note: If using Node Version Manager, change the "command": "npx" part to the full path of the executable, for example 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.

Runtime Multi-Account Authentication

If you want to support multiple Xero accounts at runtime and allow MCP clients to perform the authentication flow on demand (such as PKCE), this is the better choice. In this case, use the following configuration:

Note: If XERO_CLIENT_BEARER_TOKEN is defined, it will take precedence over XERO_CLIENT_ID.

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

Note: Some scopes are being deprecated in favor of more granular scopes. For detailed information on the deprecation timeline, please refer to the Xero OAuth 2.0 Scopes documentation.

Available MCP Commands

Query Type

list-accounts: Retrieve a list of accounts
list-contacts: Retrieve a list of contacts from Xero
list-credit-notes: Retrieve a list of credit notes
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 organisation details
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 leave records for payroll employees
list-payroll-employee-leave-balances: Retrieve leave balances for payroll employees
list-payroll-employee-leave-types: Retrieve a list of payroll leave types
list-payroll-leave-periods: Retrieve a list of leave periods for payroll employees
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: Retrieve aged receivables for a contact
list-aged-payables-by-contact: Retrieve aged payables for a contact
list-contact-groups: Retrieve a list of contact groups
list-tracking-categories: Retrieve a list of tracking categories

Create

create-bank-transaction: Create a new bank transaction
create-contact: Create a new contact
create-credit-note: Create a new credit note
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

Update

update-bank-transaction: Update an existing bank transaction
update-contact: Update an existing contact
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 in an existing payroll timesheet

Payroll Timesheet Related

approve-payroll-timesheet: Approve a payroll timesheet
revert-payroll-timesheet: Revert an approved payroll timesheet
add-payroll-timesheet-line: Add a new line to an existing payroll timesheet
delete-payroll-timesheet: Delete an existing payroll timesheet
get-payroll-timesheet: Retrieve an existing payroll timesheet

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

Integration with Claude Desktop

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

Note: On Windows, ensure that the \ between folders in the args pathis escaped, for example "C:\projects\xero-mcp-server\dist\index.js".

Security Notice

Do not commit the .env file or any sensitive credentials to version control (it is already included in .gitignore by default as a safe default).

xero-mcp-server

About this tool