mcpengine/servers/xero

Xero MCP Server

Model Context Protocol (MCP) server for Xero Accounting API integration.

Features

• Complete Xero Accounting API coverage: Invoices, Bills, Contacts, Accounts, Payments, Bank Transactions, Credit Notes, Purchase Orders, Quotes, Manual Journals, Reports, and more
• OAuth2 authentication with Bearer token
• Rate limiting: Respects Xero's 60 calls/min and 5000 calls/day limits
• Automatic retry with exponential backoff
• Pagination support: page/pageSize parameters (max 100 per page)
• If-Modified-Since header support for efficient polling
• Comprehensive TypeScript types with branded IDs (GUIDs)
• Lazy-loaded tools for optimal performance
• Dual transport support (stdio/SSE)
• Graceful shutdown

Installation

npm install
npm run build

Configuration

Create a .env file from .env.example:

cp .env.example .env

Required Environment Variables

• XERO_ACCESS_TOKEN: OAuth2 Bearer token
• XERO_TENANT_ID: Xero organization/tenant ID

Optional Environment Variables

• XERO_BASE_URL: Custom API base URL (default: https://api.xero.com/api.xro/2.0)
• XERO_TIMEOUT: Request timeout in milliseconds (default: 30000)
• XERO_RETRY_ATTEMPTS: Number of retry attempts (default: 3)
• XERO_RETRY_DELAY_MS: Retry delay in milliseconds (default: 1000)

Usage

Running the Server

npm start

Or with MCP client configuration:

{
  "mcpServers": {
    "xero": {
      "command": "node",
      "args": ["/path/to/xero/dist/main.js"],
      "env": {
        "XERO_ACCESS_TOKEN": "your_token",
        "XERO_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

Available Tools

Invoices

• xero_list_invoices - List all invoices with filtering
• xero_get_invoice - Get invoice by ID
• xero_create_invoice - Create new invoice
• xero_update_invoice - Update existing invoice

Bills (Payable Invoices)

• xero_list_bills - List all bills
• xero_create_bill - Create new bill

Contacts

• xero_list_contacts - List all contacts
• xero_get_contact - Get contact by ID
• xero_create_contact - Create new contact
• xero_update_contact - Update existing contact

Accounts (Chart of Accounts)

• xero_list_accounts - List all accounts
• xero_get_account - Get account by ID
• xero_create_account - Create new account

Bank Transactions

• xero_list_bank_transactions - List all bank transactions
• xero_get_bank_transaction - Get bank transaction by ID
• xero_create_bank_transaction - Create new bank transaction

Payments

• xero_list_payments - List all payments
• xero_create_payment - Create new payment

Credit Notes

• xero_list_credit_notes - List all credit notes
• xero_create_credit_note - Create new credit note

Purchase Orders

• xero_list_purchase_orders - List all purchase orders
• xero_create_purchase_order - Create new purchase order

Quotes

• xero_list_quotes - List all quotes
• xero_create_quote - Create new quote

Reports

• xero_get_balance_sheet - Get balance sheet report
• xero_get_profit_and_loss - Get profit & loss report
• xero_get_trial_balance - Get trial balance report
• xero_get_bank_summary - Get bank summary report

Other

• xero_list_employees - List all employees
• xero_list_tax_rates - List all tax rates
• xero_list_items - List inventory/service items
• xero_create_item - Create new item
• xero_get_organisation - Get organisation details
• xero_list_tracking_categories - List tracking categories

Filtering & Pagination

Most list endpoints support:

• page: Page number (default: 1)
• pageSize: Records per page (max: 100)
• where: Filter expression (e.g., Status=="AUTHORISED")
• order: Sort order (e.g., InvoiceNumber DESC)
• includeArchived: Include archived records

Example:

{
  "name": "xero_list_invoices",
  "arguments": {
    "where": "Status==\"AUTHORISED\" AND AmountDue > 0",
    "order": "DueDate ASC",
    "page": 1,
    "pageSize": 50
  }
}

Rate Limits

Xero enforces the following rate limits:

• 60 calls/minute per connection
• 5000 calls/day per connection

This server automatically handles rate limiting and will queue requests as needed.

Authentication

This server uses OAuth2 Bearer token authentication. You'll need to:

1. Register your app in the Xero Developer Portal
2. Complete the OAuth2 flow to obtain an access token
3. Get the tenant ID from the connections endpoint
4. Set both values in your environment variables

Note: Access tokens expire after 30 minutes. You'll need to implement token refresh logic in your application.

Error Handling

All errors are returned in the MCP tool response format:

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\": \"Error message here\"}"
    }
  ],
  "isError": true
}

Development

Type Checking

npm run typecheck

Build

npm run build

Watch Mode

npm run dev

API Coverage

This server covers the Xero Accounting API including:

• ✅ Invoices (receivable/payable)
• ✅ Contacts & Contact Groups
• ✅ Chart of Accounts
• ✅ Bank Transactions & Transfers
• ✅ Payments, Prepayments, Overpayments
• ✅ Credit Notes
• ✅ Purchase Orders
• ✅ Quotes
• ✅ Manual Journals
• ✅ Items (inventory/service)
• ✅ Tax Rates
• ✅ Employees (basic)
• ✅ Organisation Details
• ✅ Tracking Categories
• ✅ Branding Themes
• ✅ Financial Reports
• ✅ Attachments

License

MIT

Links

• Xero API Documentation
• Model Context Protocol
• MCP SDK