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
Setup
Create a Xero Account
If you do not 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.nvmversionsnodev22.14.0binnpx" 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.
Available MCP Commands
list-contacts: Retrieve a list of contacts from Xerolist-invoices: Retrieve a list of invoiceslist-accounts: Retrieve a list of accountslist-tax-rates : Retrieve a list of tax rateslist-quotes : Retrieve a list of quoteslist-credit-notes: Retrieve a list of credit noteslist-trial-balance: Retrieve a trial balance reportlist-profit-and-loss: Retrieve a profit and loss reportlist-items: Retrieve a list of itemslist-bank-transactions: Retrieve a list of bank account transactionslist-payroll-employees: Retrieve a list of Payroll Employeescreate-contact: Create a new contactcreate-invoice: Create a new invoicecreate-quote: Create a new quotecreate-credit-note: Create a new credit noteupdate-contact: Update an existing contactupdate-invoice: Update an existing draft invoiceupdate-quote: Update an existing draft quoteupdate-credit-note: Update an existing draft credit note
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:projectsxero-mcp-serverdistindex.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.)
[
{
"description": "List all contacts in Xero. This includes Suppliers and Customers.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "list-contacts"
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"contactIds": {
"items": {
"type": "string"
},
"type": "array"
},
"invoiceNumbers": {
"items": {
"type": "string"
},
"type": "array"
},
"page": {
"type": "number"
}
},
"required": [
"page"
],
"type": "object"
},
"name": "list-invoices"
},
{
"description": "Create a contact in Xero.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"email": {
"format": "email",
"type": "string"
},
"name": {
"type": "string"
},
"phone": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"name": "create-contact"
},
{
"description": "Create an invoice in Xero.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"contactId": {
"type": "string"
},
"lineItems": {
"items": {
"additionalProperties": false,
"properties": {
"accountCode": {
"type": "string"
},
"description": {
"type": "string"
},
"quantity": {
"type": "number"
},
"taxType": {
"type": "string"
},
"unitAmount": {
"type": "number"
}
},
"required": [
"description",
"quantity",
"unitAmount",
"accountCode",
"taxType"
],
"type": "object"
},
"type": "array"
},
"reference": {
"type": "string"
}
},
"required": [
"contactId",
"lineItems"
],
"type": "object"
},
"name": "create-invoice"
},
{
"description": "Lists all accounts in Xero. Use this tool to get the account codes and names to be used when creating invoices in Xero",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "list-accounts"
},
{
"description": "Lists all tax rates in Xero. Use this tool to get the tax rates to be used when creating invoices in Xero",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "list-tax-rates"
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"contactId": {
"type": "string"
},
"page": {
"type": "number"
}
},
"required": [
"page"
],
"type": "object"
},
"name": "list-quotes"
},
{
"description": "Create a quote in Xero.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"contactId": {
"type": "string"
},
"lineItems": {
"items": {
"additionalProperties": false,
"properties": {
"accountCode": {
"type": "string"
},
"description": {
"type": "string"
},
"quantity": {
"type": "number"
},
"taxType": {
"type": "string"
},
"unitAmount": {
"type": "number"
}
},
"required": [
"description",
"quantity",
"unitAmount",
"accountCode",
"taxType"
],
"type": "object"
},
"type": "array"
},
"quoteNumber": {
"type": "string"
},
"reference": {
"type": "string"
},
"summary": {
"type": "string"
},
"terms": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"contactId",
"lineItems"
],
"type": "object"
},
"name": "create-quote"
},
{
"description": "Update a contact in Xero.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"address": {
"additionalProperties": false,
"properties": {
"addressLine1": {
"type": "string"
},
"addressLine2": {
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"region": {
"type": "string"
}
},
"required": [
"addressLine1"
],
"type": "object"
},
"contactId": {
"type": "string"
},
"email": {
"format": "email",
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"name": {
"type": "string"
},
"phone": {
"type": "string"
}
},
"required": [
"contactId",
"name"
],
"type": "object"
},
"name": "update-contact"
},
{
"description": "Update an invoice in Xero. Only works on draft invoices.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"dueDate": {
"type": "string"
},
"invoiceId": {
"type": "string"
},
"lineItems": {
"items": {
"additionalProperties": false,
"properties": {
"accountCode": {
"type": "string"
},
"description": {
"type": "string"
},
"quantity": {
"type": "number"
},
"taxType": {
"type": "string"
},
"unitAmount": {
"type": "number"
}
},
"required": [
"description",
"quantity",
"unitAmount",
"accountCode",
"taxType"
],
"type": "object"
},
"type": "array"
},
"reference": {
"type": "string"
}
},
"required": [
"invoiceId"
],
"type": "object"
},
"name": "update-invoice"
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"contactId": {
"type": "string"
},
"page": {
"type": "number"
}
},
"required": [
"page"
],
"type": "object"
},
"name": "list-credit-notes"
},
{
"description": "Create a credit note in Xero.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"contactId": {
"type": "string"
},
"lineItems": {
"items": {
"additionalProperties": false,
"properties": {
"accountCode": {
"type": "string"
},
"description": {
"type": "string"
},
"quantity": {
"type": "number"
},
"taxType": {
"type": "string"
},
"unitAmount": {
"type": "number"
}
},
"required": [
"description",
"quantity",
"unitAmount",
"accountCode",
"taxType"
],
"type": "object"
},
"type": "array"
},
"reference": {
"type": "string"
}
},
"required": [
"contactId",
"lineItems"
],
"type": "object"
},
"name": "create-credit-note"
}
]