Xero Model Context Protocol (MCP) Service Implementation

This repository hosts the server component designed to translate commands from the Model Context Protocol (MCP) specification into actionable requests against the Xero Application Programming Interface (API). It serves as an abstraction layer for accessing core accounting functionalities.

Core Capabilities

Authentication: Implements robust OAuth 2.0 flows supporting custom credential configurations.
Entity Management: Comprehensive routines for handling client records (Contacts).
Financial Structure: Functionality for querying and manipulating the Chart of Accounts.
Billing Operations: End-to-end management of customer invoices and associated documents.
Protocol Adherence: Full commitment to the defined MCP interface standards.

Prerequisites for Deployment

A minimum Node.js runtime version of 18 or newer.
Package management utility: npm or pnpm.
Valid credentials obtained from a registered Xero Developer Application.

Reference Material and External Links

Initial Configuration Steps

Establishing a Xero Organization Account

If you lack an organization, sign up via the official portal to initiate a trial period.

Recommendation: Begin operations using a Demo Company. This environment includes pre-populated sample data for immediate testing. Switch to this entity via the top-left selector, choosing "Demo Company". Organization country settings (relevant for specialized modules like Payroll in NZ/UK) and data resets are managed under My Xero.

Authorization Mechanisms

Two primary methods for securing API access are supported by this MCP server:

1. Direct Credential Configuration (Custom Connections)

Best suited for development, isolated testing, or integration with constrained clients (e.g., Claude Desktop) where client ID and secret can be statically provided.

Setting Up Custom Connections

Follow the official guide for generating custom connections: https://developer.xero.com/documentation/guides/oauth2/custom-connections/

Note the minimum required API permissions (scopes): Defined Scopes Reference

Integration within Claude Desktop

To embed this service within Claude Desktop, modify the settings file (claude_desktop_config.json) as follows:

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

Path Consideration for NVM Users: If utilizing Node Version Manager (nvm), replace "command": "npx" with the absolute path to the npx binary (e.g., ~/.nvm/versions/node/vX.Y.Z/bin/npx).

2. Runtime Authorization (Bearer Token)

Preferred when the system needs to manage multiple distinct Xero tenants dynamically, allowing the client application to manage external authorization flows like PKCE.

Configuration using a pre-obtained token:

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

Precedence Note: If XERO_CLIENT_BEARER_TOKEN is present, it overrides any configured XERO_CLIENT_ID.

Supported MCP Operations

This service exposes the following functionality endpoints:

Reporting & Retrieval Commands:

list-accounts: Fetches the organization's general ledger structure.
list-contacts: Enumerates all business entities.
list-credit-notes: Retrieves customer credit adjustments.
list-invoices: Accesses sales and purchase invoices.
list-items: Lists inventory/services catalog.
list-organisation-details: Pulls high-level organization metadata.
list-profit-and-loss: Generates the Income Statement report.
list-quotes: Retrieves sales quotations.
list-tax-rates: Accesses configured sales/VAT tax rates.
list-payments: Retrieves transaction settlements.
list-trial-balance: Outputs the Trial Balance report.
list-bank-transactions: Views entries from connected bank feeds.
list-aged-receivables-by-contact: Aging summary for amounts owed by clients.
list-aged-payables-by-contact: Aging summary for amounts owed to suppliers.
list-contact-groups: Retrieves predefined groupings of contacts.

Payroll Specific Queries (Requires appropriate scopes/region):

list-payroll-employees: Employee roster retrieval.
list-payroll-employee-leave: Detailed employee leave history.
list-payroll-employee-leave-balances: Current leave entitlement status.
list-payroll-employee-leave-types: Available leave classifications.
list-payroll-leave-periods: Historical leave records for an employee.
list-payroll-leave-types: Global catalogue of leave types.

Creation & Modification Commands:

create-contact: Registers a new party.
create-credit-note: Issues a new credit adjustment.
create-invoice: Generates a new sales invoice.
create-payment: Records a received payment against an invoice.
create-quote: Submits a new quotation document.
create-payroll-timesheet: Submits hours worked for payroll processing.
update-contact: Modifies an existing contact record.
update-invoice: Edits a draft invoice.
update-quote: Modifies a draft quotation.
update-credit-note: Modifies a draft credit note.
update-payroll-timesheet-line: Adjusts details within an existing timesheet.
add-payroll-timesheet-line: Appends a new line item to a timesheet.
approve-payroll-timesheet: Finalizes a timesheet for payroll run.
revert-payroll-timesheet: Unapproves a timesheet.
delete-payroll-timesheet: Removes a timesheet record.
get-payroll-timesheet: Retrieves the full details of a specific timesheet.

For comprehensive API command details, consult the MCP Specification.

Developer Toolkit

Local Compilation

Ensure the project source code is built into runnable JavaScript artifacts:

bash

Using npm

npm install npm run build

Using pnpm

pnpm install pnpm build

Connecting to Claude Desktop During Development

For local debugging, configure Claude Desktop to execute the locally compiled output:

{ "mcpServers": { "xero": { "command": "node", "args": ["[Path_To_Your_Project]/xero-mcp-server/dist/index.js"], "env": { "XERO_CLIENT_ID": "[Your_Client_ID]", "XERO_CLIENT_SECRET": "[Your_Client_Secret]" } } } }

Windows Path Note: When using Windows, ensure backslashes in the args path are properly escaped (e.g., "C:\projects\xero-mcp-server\dist\index.js").

Licensing and Security

This package is distributed under the MIT License.

Security Warning: Never commit files containing sensitive credentials (e.g., .env files) to source control. This repository's default .gitignore configuration already excludes such files for safety.