Content
# xero-expenses-mcp
MCP (Model Context Protocol) server for Xero accounting. Supports Invoices, Bills, Expenses (Bank Transactions), and Expense Claims with PKCE authentication.
## Features
- **Invoices (ACCREC)** - Create sales invoices to send to customers
- **Bills (ACCPAY)** - Create bills you'll pay later
- **Expenses** - Create "Spend Money" bank transactions for already-paid expenses
- **Expense Claims** - Create receipts and submit expense claims for reimbursement
- **Attachments** - Attach PDFs and images to invoices, bills, expenses, and receipts
- **PKCE Auth** - Desktop app OAuth flow (no client secret required)
## Installation
```bash
npx xero-expenses-mcp
```
Or install globally:
```bash
npm install -g xero-expenses-mcp
```
## Xero App Setup
1. Go to [Xero Developer Portal](https://developer.xero.com/app/manage)
2. Create a new app:
- **App name**: Your choice (e.g., "Expense Manager")
- **Integration type**: "Mobile or desktop app" (uses PKCE, no secret needed)
- **Redirect URI**: `http://localhost:3000/callback`
3. Note your **Client ID**
## Claude Code Configuration
Add to your Claude Code MCP settings:
```json
{
"mcpServers": {
"xero-expenses": {
"command": "npx",
"args": ["xero-expenses-mcp"],
"env": {
"XERO_CLIENT_ID": "YOUR_CLIENT_ID"
}
}
}
}
```
Or use the CLI:
```bash
claude mcp add xero-expenses -- npx xero-expenses-mcp
```
Then set environment variables in your shell or `.env` file.
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `XERO_CLIENT_ID` | Yes | Your Xero app's client ID |
| `XERO_CLIENT_SECRET` | No | Only for Web apps (not PKCE) |
| `XERO_REDIRECT_URI` | No | Default: `http://localhost:3000/callback` |
## Authentication
On first use, the server will open a browser for Xero OAuth. After authenticating, tokens are stored in `~/.xero-mcp/token.json`.
## Available Tools
### Accounts & Contacts
- `xero_list_accounts` - List expense accounts/categories
- `xero_list_bank_accounts` - List bank accounts
- `xero_list_contacts` - Search vendors/contacts
- `xero_list_users` - List organization users (for expense claims)
### Invoices (Accounts Receivable)
- `xero_create_invoice` - Create a sales invoice to send to customers
- `xero_attach_file_to_invoice` - Attach file to an invoice
### Bills (Accounts Payable)
- `xero_create_bill` - Create a bill for future payment
- `xero_attach_file` - Attach file to a bill
### Expenses (Bank Transactions)
- `xero_create_expense` - Create a "Spend Money" transaction
- `xero_attach_file_to_expense` - Attach file to an expense
### Expense Claims (deprecated Feb 2026)
- `xero_create_expense_claim` - Create receipt + expense claim
- `xero_attach_file_to_receipt` - Attach file to a receipt
## Example Usage
In Claude Code:
```
"Create an expense for $45.50 lunch at Cafe Example on 2024-01-15, categorize as Business Meals (account 620)"
```
Claude will use the `xero_create_expense_claim` tool with:
```json
{
"vendorName": "Cafe Example",
"amount": 45.50,
"description": "Lunch",
"accountCode": "620",
"date": "2024-01-15"
}
```
## Token Storage
Tokens are stored in `~/.xero-mcp/token.json`. To re-authenticate, delete this file.
## License
MIT
