Xero MCP Interface Adapter

This repository presents a specialized implementation of the Model Context Protocol (MCP) server designed specifically for interfacing with the Xero accounting platform's extensive Application Programming Interface (API). It serves as a crucial translation layer, ensuring standardized interaction across diverse business applications utilizing the MCP standard to query and manipulate Xero data.

Core Capabilities

• Authorization Handling: Implements robust OAuth 2.0 flow management for Xero, supporting bespoke connection configurations.
• Entity Management: Full lifecycle support for organizational contacts.
• Financial Structure Control: Administration over the Chart of Accounts structure.
• Billing Operations: Capabilities for drafting and finalizing customer invoices.
• Protocol Adherence: Strict compliance with the Model Context Protocol specification.

System Requirements

To deploy and operate this adapter:

• Runtime Environment: Node.js (version 18 or superior is mandatory).
• Package Manager: npm or pnpm.
• API Access: Valid developer credentials procured from a registered Xero account.

Reference Materials & External Links

• Official Xero Public API Specification
• Interactive Xero API Exploration Tool
• Xero OpenAPI Definition Repository
• Xero-Node SDK Documentation for Accounting Endpoints
• General Xero Developer Resources

Deployment & Configuration

Initializing Your Xero Organization Account

If you lack a Xero account, registration is available via the sign-up portal, often beginning with a complimentary trial period.

Recommendation: Utilize a 'Demo Company' instance initially. These instances arrive pre-populated with representative sample data. Switching between organizations or resetting demo data is managed via the top-left organizational selector, linking to the My Xero Portal.

Crucial Note for Payroll Functions: For successful execution of payroll-related data queries, the associated Xero organization region must be configured as either New Zealand (NZ) or United Kingdom (UK).

Authentication Mechanisms

The Xero Adapter supports two primary methods for establishing secure connections:

1. Client-Specific Credentials (Custom Connections)

This method is preferred for controlled environments like dedicated testing/development setups or when integrating with external MCP clients (e.g., Claude Desktop) requiring static credentials.

Configuring Developer Credentials

Follow the official guide for setting up a Custom Connection here: https://developer.xero.com/documentation/guides/oauth2/custom-connections/

The minimum required API permissions (scopes) for all operational sessions are codified within: Authorization Scopes Definition

Integration Example for Desktop Clients (e.g., Claude)

To enable this adapter within a desktop application's configuration file (claude_desktop_config.json):

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

Path Management Note: If utilizing a Node Version Manager (like NVM), the command field must point to the absolute executable path (e.g., /Users/user/.nvm/versions/node/v22.14.0/bin/npx on Unix-like systems).

2. Runtime Authorization Token (Bearer Token)

This approach is optimal when the adapter must support dynamic authentication contexts for numerous Xero tenants, enabling the MCP client to manage the full OAuth flow (such as PKCE):

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

Precedence Rule: If both XERO_CLIENT_BEARER_TOKEN and XERO_CLIENT_ID are supplied, the Bearer Token configuration will always override the static Client ID/Secret settings.

Supported MCP Operations

This adapter exposes a comprehensive suite of commands for data retrieval and modification:

Reporting & Listing Commands:

• list-accounts: Fetch GL account definitions.
• list-contacts: Retrieve the organization's address book entries.
• list-credit-notes: Access customer credit notes.
• list-invoices: Query sales invoices.
• list-items: Catalog of inventory items.
• list-organisation-details: Obtain top-level organizational metadata.
• list-profit-and-loss: Generate the Income Statement report.
• list-quotes: Review outstanding sales quotations.
• list-tax-rates: View configured sales tax rates.
• list-payments: Detail received customer payments.
• list-trial-balance: Produce the Trial Balance ledger summary.
• list-bank-transactions: Access recorded movements in bank feeds.
• list-payroll-employees: Fetch employee registry data (requires appropriate region).
• list-report-balance-sheet: Generate the Statement of Financial Position.
• list-payroll-employee-leave: Detail specific employee leave entitlements.
• list-payroll-employee-leave-balances: View current employee leave accruals.
• list-payroll-employee-leave-types: Enumerate defined leave categories.
• list-payroll-leave-periods: Review historical leave usage records.
• list-aged-receivables-by-contact: Analyze outstanding customer debts.
• list-aged-payables-by-contact: Analyze outstanding supplier liabilities.
• list-contact-groups: List predefined customer groupings.

Creation Commands:

• create-contact: Register a new client or vendor record.
• create-credit-note: Issue a new credit note document.
• create-invoice: Generate a new sales invoice.
• create-payment: Record a payment against an invoice/bill.
• create-quote: Issue a new sales quotation.
• create-payroll-timesheet: Log employee working hours for processing.

Modification Commands:

• update-contact: Modify details of an existing contact.
• update-invoice: Amend a draft invoice record.
• update-quote: Revise an existing draft quotation.
• update-credit-note: Edit a draft credit note.
• update-payroll-timesheet-line: Modify specific entries within a timesheet.

Payroll Workflow Commands:

• approve-payroll-timesheet: Finalize a timesheet for payroll processing.
• revert-payroll-timesheet: Undo the approval status of a timesheet.
• add-payroll-timesheet-line: Append entries to an existing timesheet.
• delete-payroll-timesheet: Erase a timesheet record.
• get-payroll-timesheet: Retrieve the full details of a specific timesheet.

For exhaustive details on request structures and expected responses, consult the official MCP Protocol Specification.

Developer Utility Section

Local Installation

Use your preferred package manager to fetch dependencies:

bash

Using npm

npm install

Using pnpm

pnpm install

Building the Production Artifact

Execute the build script to compile source files:

bash

Using npm

npm run build

Using pnpm

pnpm build

Development Integration with Desktop Environments

For testing while actively developing, configure your configuration file (claude_desktop_config.json) to point directly to the built JavaScript file:

{ "mcpServers": { "xero": { "command": "node", "args": ["path/to/your/project/xero-mcp-server/dist/index.js"], "env": { "XERO_CLIENT_ID": "your_client_id_here", "XERO_CLIENT_SECRET": "your_client_secret_here" } } } }

Windows Path Note: On Windows systems, backslashes in file paths within the args array must be escaped (e.g., "C:\projects\xero-mcp-server\dist\index.js").

Licensing

Distributed under the terms of the MIT License.

Security Advisory

It is strictly prohibited to commit configuration files containing sensitive API keys or secrets (such as the .env file, which is excluded by default in .gitignore) to any public or private source control repository.