Skip to content
Back to search

xero-mcp-server

An MCP server that integrates with the MCP protocol. https://modelcontextprotocol.io/introduction

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xeroapi--xero-mcp-server/badge.svg)](/listings/xeroapi--xero-mcp-server)

HTML

<a href="/listings/xeroapi--xero-mcp-server"><img src="/api/listings/xeroapi--xero-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Create a Xero Account

If you don't already have a Xero account and organisation already, can create one by signing up [here](https://www.xero.com/au/signup/) 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](https://my.xero.com).

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](src/clients/xero-client.ts#L82-L90) (bundled permissions) | | From Apr 29, 2026 | [SCOPES_V2](src/clients/xero-client.ts#L93-L112) (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](https://github.com/nvm-sh/nvm) `"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](https://developer.xero.com/documentation/guides/oauth2/scopes/) 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 243 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Xero MCP Server
  2. 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.
  3. ## Features
  4. - Xero OAuth2 authentication with custom connections
  5. - Contact management
  6. - Chart of Accounts management
  7. - Invoice creation and management
  8. - MCP protocol compliance
  9. ## Prerequisites
  10. - Node.js (v18 or higher)
  11. - npm or pnpm
  12. - A Xero developer account with API credentials
  13. ## Docs and Links
  14. - [Xero Public API Documentation](https://developer.xero.com/documentation/api/)
  15. - [Xero API Explorer](https://api-explorer.xero.com/)
  16. - [Xero OpenAPI Specs](https://github.com/XeroAPI/Xero-OpenAPI)
  17. - [Xero-Node Public API SDK Docs](https://xeroapi.github.io/xero-node/accounting)
  18. - [Developer Documentation](https://developer.xero.com/)
  19. ## Setup
  20. ### Create a Xero Account
  21. If you don't already have a Xero account and organisation already, can create one by signing up [here](https://www.xero.com/au/signup/) using the free trial.
  22. 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](https://my.xero.com).
  23. NOTE: To use Payroll-specific queries, the region should be either NZ or UK.
  24. ### Authentication
  25. There are 2 modes of authentication supported in the Xero MCP server:
  26. #### 1. Custom Connections
  27. This is a better choice for testing and development which allows you to specify client id and secrets for a specific organisation.
  28. It is also the recommended approach if you are integrating this into 3rd party MCP clients such as Claude Desktop.
  29. ##### Configuring your Xero Developer account
  30. Set up a Custom Connection following these instructions: https://developer.xero.com/documentation/guides/oauth2/custom-connections/
  31. ##### Required Scopes
  32. Custom connections require different scopes depending on when they were created. **All scopes in the relevant list must be added to your custom connection:**
  33. | Custom Connection Created | Required Scopes |
  34. |---------------------------|-----------------|
  35. | Before Apr 29, 2026 | [SCOPES_V1](src/clients/xero-client.ts#L82-L90) (bundled permissions) |
  36. | From Apr 29, 2026 | [SCOPES_V2](src/clients/xero-client.ts#L93-L112) (granular permissions) |
  37. > **Note:** The MCP server automatically tries V1 scopes first and falls back to V2 if needed.
  38. >
  39. > You can override these by setting the `XERO_SCOPES` environment variable to a space-separated list of scopes.
  40. ##### Integrating the MCP server with Claude Desktop
  41. To add the MCP server to Claude go to Settings > Developer > Edit config and add the following to your claude_desktop_config.json file:
  42. ```json
  43. {
  44. "mcpServers": {
  45. "xero": {
  46. "command": "npx",
  47. "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
  48. "env": {
  49. "XERO_CLIENT_ID": "your_client_id_here",
  50. "XERO_CLIENT_SECRET": "your_client_secret_here",
  51. "XERO_SCOPES": "accounting.invoices accounting.contacts accounting.settings"
  52. }
  53. }
  54. }
  55. }
  56. ```
  57. The `XERO_SCOPES` variable is optional. If omitted, the default scopes listed above will be used.
  58. NOTE: If you are using [Node Version Manager](https://github.com/nvm-sh/nvm) `"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
  59. #### 2. Bearer Token
  60. 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.
  61. In this case, use the following configuration:
  62. ```json
  63. {
  64. "mcpServers": {
  65. "xero": {
  66. "command": "npx",
  67. "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
  68. "env": {
  69. "XERO_CLIENT_BEARER_TOKEN": "your_bearer_token"
  70. }
  71. }
  72. }
  73. }
  74. ```
  75. NOTE: The `XERO_CLIENT_BEARER_TOKEN` will take precedence over the `XERO_CLIENT_ID` if defined.
  76. ##### Required Scopes for Bearer Token
  77. When obtaining a bearer token, you must request the appropriate scopes. The scopes you request should be:
  78. > **Note:** Some scopes are being deprecated in favour of more granular scopes. See the [Xero OAuth 2.0 Scopes documentation](https://developer.xero.com/documentation/guides/oauth2/scopes/) for details on deprecation timelines.
  79. ```
  80. accounting.transactions (Deprecated)
  81. accounting.transactions.read (Deprecated)
  82. accounting.invoices
  83. accounting.invoices.read
  84. accounting.payments
  85. accounting.payments.read
  86. accounting.banktransactions
  87. accounting.banktransactions.read
  88. accounting.manualjournals
  89. accounting.manualjournals.read
  90. accounting.reports.read (Deprecated)
  91. accounting.reports.aged.read
  92. accounting.reports.balancesheet.read
  93. accounting.reports.profitandloss.read
  94. accounting.reports.trialbalance.read
  95. accounting.contacts
  96. accounting.settings
  97. payroll.settings
  98. payroll.employees
  99. payroll.timesheets
  100. ```
  101. ### Available MCP Commands
  102. - `list-accounts`: Retrieve a list of accounts
  103. - `list-contacts`: Retrieve a list of contacts from Xero
  104. - `list-credit-notes`: Retrieve a list of credit notes
  105. - `list-invoices`: Retrieve a list of invoices
  106. - `list-items`: Retrieve a list of items
  107. - `list-manual-journals`: Retrieve a list of manual journals
  108. - `list-organisation-details`: Retrieve details about an organisation
  109. - `list-profit-and-loss`: Retrieve a profit and loss report
  110. - `list-quotes`: Retrieve a list of quotes
  111. - `list-tax-rates`: Retrieve a list of tax rates
  112. - `list-payments`: Retrieve a list of payments
  113. - `list-trial-balance`: Retrieve a trial balance report
  114. - `list-bank-transactions`: Retrieve a list of bank account transactions
  115. - `list-payroll-employees`: Retrieve a list of Payroll Employees
  116. - `list-report-balance-sheet`: Retrieve a balance sheet report
  117. - `list-payroll-employee-leave`: Retrieve a Payroll Employee's leave records
  118. - `list-payroll-employee-leave-balances`: Retrieve a Payroll Employee's leave balances
  119. - `list-payroll-employee-leave-types`: Retrieve a list of Payroll leave types
  120. - `list-payroll-leave-periods`: Retrieve a list of a Payroll Employee's leave periods
  121. - `list-payroll-leave-types`: Retrieve a list of all available leave types in Xero Payroll
  122. - `list-timesheets`: Retrieve a list of Payroll Timesheets
  123. - `list-aged-receivables-by-contact`: Retrieves aged receivables for a contact
  124. - `list-aged-payables-by-contact`: Retrieves aged payables for a contact
  125. - `list-contact-groups`: Retrieve a list of contact groups
  126. - `list-tracking-categories`: Retrieve a list of tracking categories
  127. - `create-bank-transaction`: Create a new bank transaction
  128. - `create-contact`: Create a new contact
  129. - `create-credit-note`: Create a new credit note
  130. - `create-invoice`: Create a new invoice
  131. - `create-item`: Create a new item
  132. - `create-manual-journal`: Create a new manual journal
  133. - `create-payment`: Create a new payment
  134. - `create-quote`: Create a new quote
  135. - `create-payroll-timesheet`: Create a new Payroll Timesheet
  136. - `create-tracking-category`: Create a new tracking category
  137. - `create-tracking-option`: Create a new tracking option
  138. - `update-bank-transaction`: Update an existing bank transaction
  139. - `update-contact`: Update an existing contact
  140. - `update-invoice`: Update an existing draft invoice
  141. - `update-item`: Update an existing item
  142. - `update-manual-journal`: Update an existing manual journal
  143. - `update-quote`: Update an existing draft quote
  144. - `update-credit-note`: Update an existing draft credit note
  145. - `update-tracking-category`: Update an existing tracking category
  146. - `update-tracking-options`: Update tracking options
  147. - `update-payroll-timesheet-line`: Update a line on an existing Payroll Timesheet
  148. - `approve-payroll-timesheet`: Approve a Payroll Timesheet
  149. - `revert-payroll-timesheet`: Revert an approved Payroll Timesheet
  150. - `add-payroll-timesheet-line`: Add new line on an existing Payroll Timesheet
  151. - `delete-payroll-timesheet`: Delete an existing Payroll Timesheet
  152. - `get-payroll-timesheet`: Retrieve an existing Payroll Timesheet
  153. For detailed API documentation, please refer to the [MCP Protocol Specification](https://modelcontextprotocol.io/).
  154. ## For Developers
  155. ### Installation
  156. ```bash
  157. # Using npm
  158. npm install
  159. # Using pnpm
  160. pnpm install
  161. ```
  162. ### Run a build
  163. ```bash
  164. # Using npm
  165. npm run build
  166. # Using pnpm
  167. pnpm build
  168. ```
  169. ### Integrating with Claude Desktop
  170. 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:
  171. NOTE: For Windows ensure the `args` path escapes the `\` between folders ie. `"C:\\projects\xero-mcp-server\\dist\\index.js"`
  172. ```json
  173. {
  174. "mcpServers": {
  175. "xero": {
  176. "command": "node",
  177. "args": ["insert-your-file-path-here/xero-mcp-server/dist/index.js"],
  178. "env": {
  179. "XERO_CLIENT_ID": "your_client_id_here",
  180. "XERO_CLIENT_SECRET": "your_client_secret_here"
  181. }
  182. }
  183. }
  184. }
  185. ```
  186. ## License
  187. MIT
  188. ## Security
  189. Please do not commit your `.env` file or any sensitive credentials to version control (it is included in `.gitignore` as a safe default.)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.