Xero MCP Server
OfficialThe Xero MCP Server serves as a bridge between the MCP protocol and Xero's API, enabling standardized access to Xero's accounting and business features.
Key capabilities include:
Authentication: Supports Xero OAuth2 via custom connections or bearer tokens
Contact Management: Create, update, and list contacts (Suppliers and Customers)
Invoice Management: Create, update, and list invoices with filtering by contact or invoice number
Quote Management: Create and list quotes with optional pagination
Credit Note Management: Create and list credit notes
Account Management: List accounts to retrieve codes and names
Tax Rate Management: List tax rates for invoicing
Payment Management: Create payments
Payroll Management (NZ/UK regions): Manage timesheets, employees, and leave
Reporting: Retrieve profit and loss reports, balance sheets, and trial balances
Provides a bridge to Xero's accounting and business features, including contact management, chart of accounts management, and invoice creation and management, using OAuth2 authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Xero MCP Server list my recent invoices from the last 30 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: xero-mcp-enhanced
Prerequisites
Node.js (v18 or higher)
npm or pnpm
A Xero developer account with API credentials
Docs and Links
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_SCOPESenvironment 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.timesheetsAvailable 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 periodslist-payroll-leave-types: Retrieve a list of all available leave types in Xero Payrolllist-timesheets: Retrieve a list of Payroll Timesheetslist-aged-receivables-by-contact: Retrieves aged receivables for a contactlist-aged-payables-by-contact: Retrieves aged payables for a contactlist-contact-groups: Retrieve a list of contact groupslist-tracking-categories: Retrieve a list of tracking categoriescreate-bank-transaction: Create a new bank transactioncreate-contact: Create a new contactcreate-credit-note: Create a new credit notecreate-invoice: Create a new invoicecreate-item: Create a new itemcreate-manual-journal: Create a new manual journalcreate-payment: Create a new paymentcreate-quote: Create a new quotecreate-payroll-timesheet: Create a new Payroll Timesheetcreate-tracking-category: Create a new tracking categorycreate-tracking-option: Create a new tracking optionupdate-bank-transaction: Update an existing bank transactionupdate-contact: Update an existing contactupdate-invoice: Update an existing draft invoiceupdate-item: Update an existing itemupdate-manual-journal: Update an existing manual journalupdate-quote: Update an existing draft quoteupdate-credit-note: Update an existing draft credit noteupdate-tracking-category: Update an existing tracking categoryupdate-tracking-options: Update tracking optionsupdate-payroll-timesheet-line: Update a line on an existing Payroll Timesheetapprove-payroll-timesheet: Approve a Payroll Timesheetrevert-payroll-timesheet: Revert an approved Payroll Timesheetadd-payroll-timesheet-line: Add new line on an existing Payroll Timesheetdelete-payroll-timesheet: Delete an existing Payroll Timesheetget-payroll-timesheet: Retrieve an existing Payroll Timesheet
For detailed API documentation, please refer to the MCP Protocol Specification.
For Developers
Installation
# Using npm
npm install
# Using pnpm
pnpm installRun a build
# Using npm
npm run build
# Using pnpm
pnpm buildIntegrating 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.)
Available Tools
51 toolsadd-timesheet-lineC
Add a new timesheet line to an existing payroll timesheet in Xero.
Inputs: timesheetID (required), timesheetLine (required).
approve-timesheetC
Approve a payroll timesheet in Xero by its ID.
Inputs: timesheetID (required).
create-bank-transactionC
Create a bank transaction in Xero. When a bank transaction is created, a deep link to the bank transaction in Xero is returned. This deep link can be used to view the bank transaction in Xero directly. This link should be displayed to the user.
Inputs: type (required), contactId (required), lineItems (required), bankAccountId (required), +2 more.
create-contactB
Create a contact in Xero. When a contact is created, a deep link to the contact in Xero is returned. This deep link can be used to view the contact in Xero directly. This link should be displayed to the user.
Inputs: name (required), email, phone.
create-credit-noteC
Create a credit note in Xero. When a credit note is created, a deep link to the credit note in Xero is returned. This deep link can be used to view the credit note in Xero directly. This link should be displayed to the user.
Inputs: contactId (required), lineItems (required), reference.
create-invoiceB
Create an invoice in Xero. When an invoice is created, a deep link to the invoice in Xero is returned. This deep link can be used to view the invoice in Xero directly. This link should be displayed to the user.
Inputs: type (required), contactId (required), lineItems (required), date, +1 more.
create-itemC
Create an item in Xero.
Inputs: code (required), name (required), description, salesDetails, +4 more.
create-manual-journalB
Create a manual journal in Xero. Retrieve a list of account codes in Xero to use for the journal lines. Journal lines must contain at least two individual journal lines with account codes, use basic accounting account types pairing when not specified, and make sure journal line pairs have credit and debit balanced.
Inputs: narration (required), manualJournalLines (required), url, date, +3 more.
create-paymentA
Create a payment against an invoice in Xero. This tool records a payment transaction against an invoice. You'll need to provide the invoice ID, account ID to make the payment from, and the amount. The amount must be positive and should not exceed the remaining amount due on the invoice. A payment can only be created for an invoice that is status AUTHORIZED A payment can only be created for an invoice that is not fully paid When a payment is created, a deep link to the payment in Xero is returned. This deep link can be used to view the payment in Xero directly. This link should be displayed to the user.
Inputs: amount (required), accountId (required), invoiceId (required), date, +1 more.
create-quoteC
Create a quote in Xero. When a quote is created, a deep link to the quote in Xero is returned. This deep link can be used to view the quote in Xero directly. This link should be displayed to the user.
Inputs: contactId (required), lineItems (required), terms, title, +3 more.
create-timesheetC
Create a new payroll timesheet in Xero. This allows you to specify details such as the employee ID, payroll calendar ID, start and end dates, and timesheet lines.
Inputs: endDate (required), startDate (required), employeeID (required), payrollCalendarID (required), +1 more.
create-tracking-categoryC
Create a tracking category in Xero.
Inputs: name (required).
create-tracking-optionsC
Create tracking options for a tracking category in Xero.
Inputs: optionNames (required), trackingCategoryId (required).
delete-timesheetC
Delete an existing payroll timesheet in Xero by its ID.
Inputs: timesheetID (required).
get-timesheetA
Retrieve a single payroll timesheet from Xero by its ID. This provides details such as the timesheet ID, employee ID, start and end dates, total hours, and the last updated date.
Inputs: timesheetID (required).
list-accountsA
Lists all accounts in Xero. Use this tool to get the account codes and names to be used when creating invoices in Xero
Inputs: no named parameters.
list-aged-payables-by-contactC
Lists the aged payables in Xero. This shows aged payables for a certain contact up to a report date.
Inputs: contactId (required), reportDate, invoicesToDate, invoicesFromDate.
list-aged-receivables-by-contactC
Lists the aged receivables in Xero. This shows aged receivables for a certain contact up to a report date.
Inputs: contactId (required), reportDate, invoicesToDate, invoicesFromDate.
list-bank-transactionsB
List all bank transactions in Xero. Ask the user if they want to see bank transactions for a specific bank account, or to see all bank transactions before running. Ask the user if they want the next page of quotes after running this tool if 10 bank transactions are returned. If they do, call this tool again with the next page number and the bank account if one was provided in the provided in the previous call.
Inputs: page (required), bankAccountId.
list-contact-groupsB
List all contact groups in Xero. You can optionally specify a contact group ID to retrieve details for that specific group, including its contacts.
Inputs: contactGroupId.
list-contactsC
List all contacts in Xero. This includes Suppliers and Customers.
Inputs: page, searchTerm.
list-credit-notesA
List credit notes in Xero. Ask the user if they want to see credit notes for a specific contact, or to see all credit notes before running. Ask the user if they want the next page of credit notes after running this tool if 10 credit notes are returned. If they want the next page, call this tool again with the next page number and the contact if one was provided in the previous call.
Inputs: page (required), contactId.
list-invoicesA
List invoices in Xero. This includes Draft, Submitted, and Paid invoices. Ask the user if they want to see invoices for a specific contact, invoice number, or to see all invoices before running. Ask the user if they want the next page of invoices after running this tool if 10 invoices are returned. If they want the next page, call this tool again with the next page number and the contact or invoice number if one was provided in the previous call.
Inputs: page (required), contactIds, invoiceNumbers.
list-itemsB
Lists all items in Xero. Use this tool to get the item codes and descriptions to be used when creating invoices in Xero
Inputs: page (required).
list-manual-journalsC
List all manual journals from Xero. Ask the user if they want to see a specific manual journal or all manual journals before running. Can optionally pass in manual journal ID to retrieve a specific journal, or a date to filter journals modified after that date. The response presents a complete overview of all manual journals currently registered in your Xero account, with their details. Ask the user if they want the next page of manual journals after running this tool if 10 manual journals are returned. If they want the next page, call this tool again with the next page number, modified date, and the manual journal ID if one was provided in the previous call.
Inputs: page, modifiedAfter, manualJournalId.
list-organisation-detailsB
Lists the organisation details from Xero. Use this tool to get information about the current Xero organisation.
Inputs: no named parameters.
list-paymentsA
List payments in Xero. This tool shows all payments made against invoices, including payment date, amount, and payment method. You can filter payments by invoice number, invoice ID, payment ID, or invoice reference. Ask the user if they want to see payments for a specific invoice, contact, payment or reference before running. If many payments are returned, ask the user if they want to see the next page.
Inputs: page, invoiceId, paymentId, reference, +1 more.
list-payroll-employee-leaveB
List all leave records for a specific employee in Xero. This shows all leave transactions including approved, pending, and processed time off. Provide an employee ID to see their leave history.
Inputs: employeeId (required).
list-payroll-employee-leave-balancesC
List all leave balances for a specific employee in Xero. This shows current leave balances for all leave types available to the employee, including annual, sick, and other leave types.
Inputs: employeeId (required).
list-payroll-employee-leave-typesB
List all leave types available for a specific employee in Xero. This shows detailed information about the types of leave an employee can take, including schedule of accrual, leave type name, and entitlement.
Inputs: employeeId (required).
list-payroll-employeesA
List all payroll employees in Xero. This retrieves comprehensive employee details including names, User IDs, dates of birth, email addresses, gender, phone numbers, start dates, engagement types (Permanent, FixedTerm, or Casual), titles, and when records were last updated. The response presents a complete overview of all staff currently registered in your Xero payroll, with their personal and employment information. If there are many employees, ask the user if they would like to see more detailed information about specific employees before proceeding.
Inputs: no named parameters.
list-payroll-leave-periodsA
List all leave periods for a specific employee in Xero. This shows detailed time off periods including start and end dates, period status, payment dates, and leave types. Provide an employee ID to see their leave periods.
Inputs: employeeId (required), endDate, startDate.
list-payroll-leave-typesB
Lists all available leave types in Xero Payroll. This provides information about all the leave categories configured in your Xero system, including statutory and organization-specific leave types.
Inputs: no named parameters.
list-profit-and-lossC
Lists profit and loss report in Xero. This provides a summary of revenue, expenses, and profit or loss over a specified period of time.
Inputs: toDate, periods, fromDate, timeframe, +2 more.
list-quotesA
List all quotes in Xero. Ask the user if they want to see quotes for a specific contact before running. Ask the user if they want the next page of quotes after running this tool if 10 quotes are returned. If they do, call this tool again with the page number and the contact provided in the previous call.
Inputs: page (required), contactId, quoteNumber.
list-report-balance-sheetC
List the Balance Sheet report from Xero.
Inputs: date, periods, timeframe, paymentsOnly, +3 more.
list-tax-ratesA
Lists all tax rates in Xero. Use this tool to get the tax rates to be used when creating invoices in Xero
Inputs: no named parameters.
list-timesheetsB
List all payroll timesheets in Xero. This retrieves comprehensive timesheet details including timesheet IDs, employee IDs, start and end dates, total hours, and the last updated date.
Inputs: no named parameters.
list-tracking-categoriesB
List all tracking categories in Xero, along with their associated tracking options.
Inputs: includeArchived.
list-trial-balanceB
Lists trial balance in Xero. This provides a snapshot of the general ledger, showing debit and credit balances for each account.
Inputs: date, paymentsOnly.
revert-timesheetC
Revert a payroll timesheet to draft in Xero by its ID.
Inputs: timesheetID (required).
update-bank-transactionC
Update a bank transaction in Xero. When a bank transaction is updated, a deep link to the bank transaction in Xero is returned. This deep link can be used to view the bank transaction in Xero directly. This link should be displayed to the user.
Inputs: bankTransactionId (required), date, type, contactId, +2 more.
update-contactC
Update a contact in Xero. When a contact is updated, a deep link to the contact in Xero is returned. This deep link can be used to view the contact in Xero directly. This link should be displayed to the user.
Inputs: name (required), contactId (required), email, phone, +3 more.
update-credit-noteA
Update a credit note in Xero. Only works on draft credit notes. All line items must be provided. Any line items not provided will be removed. Including existing line items. Do not modify line items that have not been specified by the user. When a credit note is updated, a deep link to the credit note in Xero is returned. This deep link can be used to view the credit note in Xero directly. This link should be displayed to the user.
Inputs: creditNoteId (required), date, contactId, lineItems, +1 more.
update-invoiceA
Update an invoice in Xero. Only works on draft invoices. All line items must be provided. Any line items not provided will be removed. Including existing line items. Do not modify line items that have not been specified by the user. When an invoice is updated, a deep link to the invoice in Xero is returned. This deep link can be used to view the contact in Xero directly. This link should be displayed to the user.
Inputs: invoiceId (required), date, dueDate, contactId, +2 more.
update-itemC
Update an item in Xero.
Inputs: code (required), name (required), itemId (required), description, +5 more.
update-manual-journalB
Update a manual journal in Xero. Only works on draft manual journals. Do not modify line items or parameters that have not been specified by the user.
Inputs: narration (required), manualJournalID (required), manualJournalLines (required), url, +4 more.
update-quoteA
Update a quote in Xero. Only works on draft quotes. All line items must be provided. Any line items not provided will be removed. Including existing line items. Do not modify line items that have not been specified by the user. When a quote is updated, a deep link to the quote in Xero is returned. This deep link can be used to view the quote in Xero directly. This link should be displayed to the user.
Inputs: quoteId (required), date, terms, title, +6 more.
update-timesheet-lineC
Update an existing timesheet line in a payroll timesheet in Xero.
Inputs: timesheetID (required), timesheetLine (required), timesheetLineID (required).
update-tracking-categoryC
Updates an existing tracking category in Xero.
Inputs: trackingCategoryId (required), name, status.
update-tracking-optionsC
Updates tracking options for a tracking category in Xero.
Inputs: options (required), trackingCategoryId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 51 tools
Most tools map to distinct Xero resources and actions, and the descriptions make similar payroll/leave and reporting tools reasonably separable. A few areas overlap, especially the multiple payroll leave list tools and list-vs-filter patterns, but overall an agent can tell them apart.
Tool names consistently use kebab-case verb-resource patterns such as create-invoice, list-contacts, update-item, and delete-timesheet. Minor variations like list-report-balance-sheet are still readable and fit the same overall convention.
With 51 tools, the surface is far above the ideal 3-15 range and will make tool selection harder for an agent. The breadth reflects the Xero accounting domain, but the set is still too large for a single MCP server without stronger grouping or consolidation.
Core create/list/update flows are well represented across invoices, contacts, items, quotes, credit notes, bank transactions, and payroll timesheets. However, delete operations are missing for most resources, direct get-by-ID tools are absent for almost everything except timesheets, and create-timesheet requires a payroll calendar ID even though no tool lists payroll calendars.
Maintenance
Related MCP Connectors
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
MCP server for Codat — companies, connections, invoices, bills and financial statements.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseBqualityBmaintenanceAn MCP server allowing Clients to interact with Xero Accounting Software15176 npm22MIT
- AlicenseNot gradedqualityDmaintenanceAn enhanced MCP server for Xero, enabling natural language interaction with your Xero organisation for accounting tasks like invoices, contacts, bank transactions, and payroll.MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that enables AI assistants to read and write Xero accounting data, including invoices, contacts, accounts, and payments, through natural language.MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for integrating Xero with GenAI applications.-