TEAMnetwork Xero MCP Server

A Model Context Protocol (MCP) server for Xero, maintained by TEAMnetwork. Forked and extended from the official Xero MCP Server.

Provides AI agents and MCP-compatible clients (e.g. Claude Desktop) with tools to read and write Xero accounting data, manage invoice attachments, and download invoice PDFs.

Features

• Invoices — create, list (with status/date filters), update, authorise, void, get full detail, download as PDF
• Contacts — create, list, update, archive
• Quotes — create, list, update, convert to invoice
• Payments & Credit Notes — create, list, update
• Bank Transactions & Manual Journals — create, list, update
• Accounts, Items, Tax Rates, Tracking — list, create, update
• Financial Reports — Trial Balance, Profit & Loss, Balance Sheet, Aged Payables/Receivables
• Invoice Attachments — list, upload (e.g. Crystal Reports PDFs), download, delete
• Payroll — employees, leave, timesheets (optional, off by default)
• Modular scopes — only request the Xero API permissions your use case needs

Prerequisites

• Node.js v18 or higher
• A Xero developer account with API credentials

Docs and Links

• Xero Public API Documentation
• Xero API Explorer
• Xero-Node SDK Docs
• MCP Protocol Specification

Setup

1. Create a Xero Developer App

Set up a Custom Connection following Xero's guide: https://developer.xero.com/documentation/guides/oauth2/custom-connections/

When configuring scopes in your Xero app, include the scopes for the feature groups you plan to use (see Feature Groups below). At minimum you need:

accounting.transactions
accounting.contacts
accounting.settings
accounting.attachments

2. Authentication

There are two authentication modes:

Custom Connections (recommended)

Uses a Client ID and Secret tied to a specific Xero organisation. Best for Claude Desktop and single-org setups.

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "tn-xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Bearer Token

Use when your MCP client handles the OAuth flow (e.g. PKCE). The bearer token takes precedence over Client ID/Secret if both are set.

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "tn-xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

When obtaining a bearer token, request the scopes matching your enabled feature groups. See Feature Groups for the full scope list.

Feature Groups

Scopes and tools are controlled by environment variables. This means you only provision the Xero API permissions your setup actually needs.

| Variable | Default | Scopes requested | Tools enabled | |---|---|---|---| | (core — always on) | — | accounting.transactions accounting.contacts accounting.settings accounting.attachments | All invoicing, contact, payment, attachment & PDF tools | | XERO_ENABLE_REPORTS | true | accounting.reports.read | Trial Balance, P&L, Balance Sheet, Aged Payables/Receivables | | XERO_ENABLE_PAYROLL | false | payroll.settings payroll.employees payroll.timesheets | All payroll tools |

Note: To use payroll tools, your Xero region must be NZ or UK, and your Xero app must have the payroll scopes provisioned.

Full configuration example

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "tn-xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here",
        "XERO_ENABLE_REPORTS": "true",
        "XERO_ENABLE_PAYROLL": "false",
        "XERO_DOWNLOAD_PATH": "C:/Users/you/Downloads/Xero"
      }
    }
  }
}

XERO_DOWNLOAD_PATH

The local directory where downloaded invoice PDFs and attachments are saved. Defaults to ~/Downloads if not set.

Available Tools

Invoices

| Tool | Description | |---|---| | list-invoices | List invoices with optional filters: status, contact, invoice number, date range | | get-invoice | Get full details of a single invoice including all line items | | create-invoice | Create a new draft invoice (AR or AP) | | update-invoice | Update a draft invoice | | authorise-invoice | Promote a DRAFT or SUBMITTED invoice to AUTHORISED | | void-invoice | Void an AUTHORISED invoice, or delete a DRAFT invoice | | get-invoice-pdf | Download the Xero-generated invoice PDF to local disk | | list-invoice-attachments | List all file attachments on an invoice | | upload-invoice-attachment | Upload a local file (e.g. Crystal Reports PDF) as an invoice attachment | | get-invoice-attachment | Download an invoice attachment to local disk | | delete-invoice-attachment | Delete an attachment from an invoice |

Quotes

| Tool | Description | |---|---| | list-quotes | List quotes | | create-quote | Create a new quote | | update-quote | Update an existing quote | | convert-quote-to-invoice | Convert a quote into a draft invoice, copying all line items |

Contacts

| Tool | Description | |---|---| | list-contacts | List contacts with optional search term | | create-contact | Create a new contact | | update-contact | Update an existing contact | | archive-contact | Archive a contact (Xero does not support hard deletion) | | list-contact-groups | List contact groups |

Payments & Credit Notes

| Tool | Description | |---|---| | list-payments | List payments | | create-payment | Record a payment against an invoice | | list-credit-notes | List credit notes | | create-credit-note | Create a credit note | | update-credit-note | Update a draft credit note |

Bank & Journals

| Tool | Description | |---|---| | list-bank-transactions | List bank transactions | | create-bank-transaction | Create a bank transaction | | update-bank-transaction | Update a bank transaction | | list-manual-journals | List manual journals | | create-manual-journal | Create a manual journal | | update-manual-journal | Update a manual journal |

Settings & Configuration

| Tool | Description | |---|---| | list-accounts | List chart of accounts | | list-tax-rates | List tax rates | | list-items | List inventory items | | create-item | Create an inventory item | | update-item | Update an inventory item | | list-tracking-categories | List tracking categories and options | | create-tracking-category | Create a tracking category | | update-tracking-category | Update a tracking category | | update-tracking-options | Update tracking options | | create-tracking-option | Create a tracking option | | list-organisation-details | Get organisation details |

Financial Reports (requires XERO_ENABLE_REPORTS=true)

| Tool | Description | |---|---| | list-trial-balance | Trial balance report | | list-profit-and-loss | Profit and loss report | | list-report-balance-sheet | Balance sheet report | | list-aged-receivables-by-contact | Aged receivables for a contact | | list-aged-payables-by-contact | Aged payables for a contact |

Payroll (requires XERO_ENABLE_PAYROLL=true)

| Tool | Description | |---|---| | list-payroll-employees | List payroll employees | | list-payroll-employee-leave | List an employee's leave records | | list-payroll-employee-leave-balances | List an employee's leave balances | | list-payroll-employee-leave-types | List leave types for an employee | | list-payroll-leave-periods | List leave periods for an employee | | list-payroll-leave-types | List all available leave types | | list-timesheets | List timesheets | | create-payroll-timesheet | Create a timesheet | | add-payroll-timesheet-line | Add a line to a timesheet | | update-payroll-timesheet-line | Update a timesheet line | | approve-payroll-timesheet | Approve a timesheet | | revert-payroll-timesheet | Revert an approved timesheet | | delete-timesheet | Delete a timesheet | | get-payroll-timesheet | Get a timesheet by ID |

For Developers

Local development setup

git clone https://github.com/your-org/tn-xero-mcp-server.git
cd tn-xero-mcp-server
npm install
cp .env.example .env
# Edit .env with your credentials
npm run build

Linking to Claude Desktop for development

In your claude_desktop_config.json, point directly at the built file:

{
  "mcpServers": {
    "xero": {
      "command": "node",
      "args": ["C:\\Users\\you\\Development\\Xero-MCP\\dist\\index.js"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here",
        "XERO_ENABLE_PAYROLL": "false",
        "XERO_DOWNLOAD_PATH": "C:\\Users\\you\\Downloads\\Xero"
      }
    }
  }
}

Windows note: Backslashes in args paths must be escaped as \\.

Publishing updates

npm run build
npm publish

License

MIT

Security

Do not commit your .env file or any credentials to version control. The .gitignore excludes .env by default.