Xero MCP server for AI agents

The Xero MCP Server provides a bridge between the Model Context Protocol and Xero's API, enabling standardized access to Xero's accounting and business features. It allows you to manage contacts, chart of accounts, invoices, and more through the MCP protocol.

Prerequisites

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

Setup

Creating a Xero Account

If you don't have a Xero account already:

Sign up for a free trial at https://www.xero.com/au/signup/
We recommend using a Demo Company to start, as it includes pre-loaded sample data
Once logged in, switch to it using the top left-hand dropdown and selecting "Demo Company"
You can reset the data or change the country for a Demo Company at any time via My Xero

Note: For Payroll-specific queries, set the region to either NZ or UK.

Authentication Options

The server supports two authentication methods:

Option 1: Custom Connections (Recommended for Testing)

This approach is ideal for development and works well with third-party MCP clients like Claude Desktop.

Setting Up Your Xero Developer Account

Create a Custom Connection by following the instructions at: https://developer.xero.com/documentation/guides/oauth2/custom-connections/
Make sure to include all required scopes for your application

Integrating with Claude Desktop

Add the MCP server to Claude Desktop by editing your configuration:

Go to Settings > Developer > Edit config
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 for NVM users: If you're using Node Version Manager, change the "command": "npx" to use the full path to the executable:

Mac/Linux: your_home_directory/.nvm/versions/node/v22.14.0/bin/npx
Windows: your_home_directory\\.nvm\\versions\\node\\v22.14.0\\bin\\npx

Option 2: Bearer Token

Better for supporting multiple Xero accounts at runtime:

{
  "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 takes precedence over XERO_CLIENT_ID if both are defined.

Available Commands

Listing and Retrieving Information

list-accounts - Retrieve chart of accounts
list-contacts - Retrieve contacts from Xero
list-credit-notes - Retrieve credit notes
list-invoices - Retrieve invoices
list-items - Retrieve items/products
list-organisation-details - Retrieve organization info
list-profit-and-loss - Retrieve profit and loss report
list-quotes - Retrieve quotes
list-tax-rates - Retrieve tax rates
list-payments - Retrieve payments
list-trial-balance - Retrieve trial balance report
list-bank-transactions - Retrieve bank transactions
list-payroll-employees - Retrieve payroll employees
list-report-balance-sheet - Retrieve balance sheet report
list-payroll-employee-leave - Retrieve employee leave records
list-payroll-employee-leave-balances - Retrieve employee leave balances
list-payroll-employee-leave-types - Retrieve employee leave types
list-payroll-leave-periods - Retrieve employee leave periods
list-payroll-leave-types - Retrieve all available leave types
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 contact groups

Creating Records

create-contact - Create a new contact
create-credit-note - Create a new credit note
create-invoice - Create a new invoice
create-payment - Create a new payment
create-quote - Create a new quote
create-payroll-timesheet - Create a payroll timesheet

Updating Records

update-contact - Update an existing contact
update-invoice - Update a draft invoice
update-quote - Update a draft quote
update-credit-note - Update a draft credit note
update-payroll-timesheet-line - Update a timesheet line

Payroll Operations

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

For more detailed information about these commands and their parameters, refer to the MCP Protocol Specification.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "xero" '{"command":"npx","args":["-y","@xeroapi/xero-mcp-server@latest"],"env":{"XERO_CLIENT_ID":"${XERO_CLIENT_ID}","XERO_CLIENT_SECRET":"${XERO_CLIENT_SECRET}"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "xero": {
            "command": "npx",
            "args": [
                "-y",
                "@xeroapi/xero-mcp-server@latest"
            ],
            "env": {
                "XERO_CLIENT_ID": "${XERO_CLIENT_ID}",
                "XERO_CLIENT_SECRET": "${XERO_CLIENT_SECRET}"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "xero": {
            "command": "npx",
            "args": [
                "-y",
                "@xeroapi/xero-mcp-server@latest"
            ],
            "env": {
                "XERO_CLIENT_ID": "${XERO_CLIENT_ID}",
                "XERO_CLIENT_SECRET": "${XERO_CLIENT_SECRET}"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect