AI and accounting automation illustration

How I Connected Xero to AI Using the Xero MCP Server

By Amjid Ali

A Step-by-Step Guide to AI-Powered Accounting Automation

Managing accounting data through natural language may sound futuristic, but with the Model Context Protocol (MCP) and Xero’s API, it is already achievable.

In this guide, I will walk you through how I set up the Xero MCP Server, connected it to my Xero organisation, and started querying invoices, contacts, and financial reports using an AI-driven interface.

What is MCP (Model Context Protocol)?

The Model Context Protocol (MCP) is an open standard that enables AI systems to interact with external tools and data sources.

It acts as a bridge between AI models and business systems. An MCP server exposes structured functions, referred to as tools, that allow AI to perform actions such as retrieving data, creating records, or executing workflows.

The Xero MCP Server wraps Xero’s API into 51 structured tools, enabling capabilities such as invoice management, contact handling, and financial reporting.

Prerequisites

Before getting started, ensure you have the following:

  • Node.js version 18 or later
  • A Xero account
  • Access to the Xero Developer Portal
  • An MCP-compatible client such as mcporter CLI or Claude Desktop
  • Basic familiarity with terminal usage

Step 1: Clone and Build the Xero MCP Server

Clone the repository and install dependencies:

git clone https://github.com/XeroAPI/xero-mcp-server.git
cd xero-mcp-server
npm install
npm run build

After the build process, the compiled application will be available in the dist/ directory. The entry point is dist/index.js.

Step 2: Create a Xero Custom Connection App

This is a critical step.

The Xero MCP Server uses the client credentials OAuth2 flow, which requires creating a Custom Connection app rather than a standard OAuth application.

Steps to follow:

  1. Go to the Xero Developer Portal
  2. Create a new app
  3. Select Custom Connection as the app type (with an HTTPS app URL)
  4. Provide a name for the application
  5. Enable the required scopes:
    • accounting.transactions
    • accounting.settings.read
    • accounting.contacts
    • accounting.invoices
    • quotes
    • credit_notes
    • accounting.chart_of_accounts.read
  6. Connect the app to your Xero organisation
  7. Copy the Client ID and Client Secret

If the required scopes are not enabled, the system will authenticate successfully but fail during API calls with an invalid_scope error.

Step 3: Configure Environment Variable

Create a .env file in the project root and define the following variables:

XERO_CLIENT_ID=your_client_id
XERO_CLIENT_SECRET=your_client_secret
XERO_TENANT_ID=your_tenant_id

The Tenant ID can be obtained from the Xero Developer Portal under your connected organisation.

Step 4: Verify the Server

Test the server with the following command:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/index.js

A valid response confirms that the server is running correctly.

Step 5: Register with an MCP Client

Using mcporter CLI

Register the server with explicit environment variables:

mcporter config add xero \
  --command node \
  --arg /path/to/dist/index.js \
  --env "XERO_CLIENT_ID=your_client_id" \
  --env "XERO_CLIENT_SECRET=your_client_secret" \
  --env "XERO_TENANT_ID=your_tenant_id"

Passing environment variables explicitly ensures consistent execution, especially when the working directory differs from the project root.

Using Claude Desktop

Add the following configuration:

{
  "mcpServers": {
    "xero": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id",
        "XERO_CLIENT_SECRET": "your_client_secret",
        "XERO_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

Step 6: Query Xero Using AI

Once connected, you can interact with Xero using structured commands or natural language.

Tip: keep invoices and quotes in DRAFT until a human reviews and approves them.

Examples:

List contacts:

mcporter call xero.list-contacts page=1

Fetch invoices:

mcporter call xero.list-invoices page=1

Retrieve a balance sheet:

mcporter call xero.list-report-balance-sheet date="2026-03-26"

You can also analyse outstanding invoices and overdue payments by combining filters and queries.

Available Capabilities

Category Capabilities
Create Contacts, invoices, payments, journals
List Reports, accounts, tax rates
Update Contacts, invoices
Delete Payroll timesheets
Get Payroll data

Troubleshooting

Environment Variables Not Found

Ensure environment variables are passed explicitly if .env is not being detected.

Failed to Get Token

This is typically caused by missing scopes. Enable the required scopes in the Xero Developer Portal.

invalid_scope Error

Verify that the app is created as a Custom Connection and that all required scopes are enabled.

Server Exits Immediately

This behaviour is expected. The server uses standard input/output transport and terminates when no input is received.

Conclusion

The integration of MCP with Xero introduces a more efficient way to interact with financial systems.

Instead of manually navigating dashboards and generating reports, users can query, analyse, and automate workflows through AI.

This approach enables:

  • Automated bookkeeping workflows
  • Real-time financial insights
  • Improved operational efficiency

The shift from traditional software interaction to AI-driven workflows is already underway, and MCP represents a foundational layer in this transformation.

Leave a Comment