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/
Required Scopes
Custom connections require different scopes depending on when they were created. All scopes in the relevant list must be added to your custom connection:
| Custom Connection Created | Required Scopes |
|---|
| Before Apr 29, 2026 | SCOPES_V1 (bundled permissions) |
| From Apr 29, 2026 | SCOPES_V2 (granular permissions) |
Note: The MCP server automatically tries V1 scopes first and falls back to V2 if needed.
You can override these by setting the XERO_SCOPES environment variable to a space-separated list of 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",
"XERO_SCOPES": "accounting.invoices accounting.contacts accounting.settings"
}
}
}
}
The XERO_SCOPES variable is optional. If omitted, the default scopes listed above will be used.
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.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
payroll.settings
payroll.employees
payroll.timesheets
Available MCP Commands
list-accounts: Retrieve a list of accountslist-contacts: Retrieve a list of contacts from Xerolist-credit-notes: Retrieve a list of credit noteslist-invoices: Retrieve a list of invoiceslist-items: Retrieve a list of itemslist-manual-journals: Retrieve a list of manual journalslist-organisation-details: Retrieve details about an organisationlist-profit-and-loss: Retrieve a profit and loss reportlist-quotes: Retrieve a list of quoteslist-tax-rates: Retrieve a list of tax rateslist-payments: Retrieve a list of paymentslist-trial-balance: Retrieve a trial balance reportlist-bank-transactions: Retrieve a list of bank account transactionslist-payroll-employees: Retrieve a list of Payroll Employeeslist-report-balance-sheet: Retrieve a balance sheet reportlist-payroll-employee-leave: Retrieve a Payroll Employee's leave recordslist-payroll-employee-leave-balances: Retrieve a Payroll Employee's leave balanceslist-payroll-employee-leave-types: Retrieve a list of Payroll leave typeslist-payroll-leave-periods: Retrieve a list of a Payroll Employee's leave periods
For detailed API documentation, please refer to the MCP Protocol Specification.
Installation
# Using npm
npm install
# Using pnpm
pnpm install