mcpengine/servers/xero/README.md

# 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

```bash
npm install
npm run build
```

## Configuration

Create a `.env` file from `.env.example`:

```bash
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

```bash
npm start
```

Or with MCP client configuration:

```json
{
  "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:
```json
{
  "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:

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

## Development

### Type Checking

```bash
npm run typecheck
```

### Build

```bash
npm run build
```

### Watch Mode

```bash
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](https://developer.xero.com/documentation/api/accounting/overview)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP SDK](https://github.com/modelcontextprotocol/sdk)