Xero Model Context Protocol Gateway

This component serves as an implementation of the Model Context Protocol (MCP) gateway tailored specifically for interfacing with the Xero Financial Platform API. It establishes a standardized abstraction layer, enabling external systems to interact with Xero's comprehensive suite of accounting and business functionalities.

Core Capabilities

• Authentication via Xero OAuth2, supporting bespoke connection configurations.
• Management of client/vendor entities (Contacts).
• Manipulation of the Chart of Accounts structure.
• End-to-end lifecycle management for customer invoices.
• Strict adherence to the defined MCP operational specification.

System Requirements

• Runtime environment: Node.js (version 18 or later recommended).
• Package manager: npm or pnpm.
• Prerequisite: Valid developer access credentials secured from a Xero developer portal.

Reference Materials

• Official Xero Public API Specification
• Interactive Xero API Exploration Tool
• Xero OpenAPI Specification Repository
• Xero-Node SDK Documentation (Accounting)
• General Developer Portal

Initial Setup Procedures

Establishing a Xero Tenancy

If you lack an active Xero organization, you may establish one by registering via the sign-up portal utilizing the complimentary trial period.

Recommendation: Begin development using a 'Demo Company,' which is pre-populated with sample financial data. This organization can be switched via the top-left selector post-login. Organizational settings, including regional data residency, are adjustable in the My Xero section.

Note on Payroll: For executing queries related to Payroll functionality, the associated region must be configured as either 'NZ' or 'UK'.

Authentication Strategies

Two primary methods are supported for securing interaction with the Xero MCP Server:

1. Custom Connection Mode (Client Credentials)

This approach is favored for development, sandbox testing, and scenarios where the MCP client (e.g., Claude Desktop) needs to manage specific organization credentials directly.

Configuration of Developer Credentials

Follow the official guide to establish a Custom Connection: https://developer.xero.com/documentation/guides/oauth2/custom-connections/

The requisite permissions (scopes) for standard operation are fixed and can be found here: Scope Definitions

Integration into Claude Desktop

To incorporate this gateway into Claude Desktop, navigate to Settings > Developer > Edit config and append the following structure to your claude_desktop_config.json file:

{ "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 Caveat (NVM Users): If utilizing Node Version Manager (NVM), the "command": "npx" entry must be replaced with the absolute path to the npx executable (e.g., /home/user/.nvm/versions/node/v22.14.0/bin/npx on Unix-like systems, or the corresponding Windows path).

2. Bearer Token Mode (Runtime Authorization)

This option is suitable when the system needs to facilitate dynamic authorization flows (like PKCE) for multiple organizations concurrently, letting the MCP client handle the full OAuth handshake.

Use the following configuration structure, supplying a pre-generated token:

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

Precedence Rule: The presence of XERO_CLIENT_BEARER_TOKEN overrides any values set for XERO_CLIENT_ID or XERO_CLIENT_SECRET during execution.

Supported MCP Operations

Below is the catalog of accessible endpoints provided by this gateway:

Read Operations:

• list-accounts: Fetch organizational chart of accounts.
• list-contacts: Retrieve all associated business entities.
• list-credit-notes: Access customer credit memos.
• list-invoices: Query outstanding and paid invoices.
• list-items: Enumerate inventory or service items.
• list-organisation-details: Obtain high-level organizational metadata.
• list-profit-and-loss: Generate the Income Statement report.
• list-quotes: View issued sales quotations.
• list-tax-rates: Fetch applicable sales/purchase tax configurations.
• list-payments: Review transaction settlements.
• list-trial-balance: Produce the Trial Balance report.
• list-bank-transactions: Fetch records from linked bank accounts.
• list-payroll-employees: Retrieve personnel records (Payroll).
• list-report-balance-sheet: Generate the Balance Sheet statement.
• list-payroll-employee-leave: Fetch specific employee leave records (Payroll).
• list-payroll-employee-leave-balances: Query current leave entitlements per employee (Payroll).
• list-payroll-employee-leave-types: List defined leave categories (Payroll).
• list-payroll-leave-periods: Retrieve historical leave usage periods (Payroll).
• list-aged-receivables-by-contact: Summarize money owed by clients.
• list-aged-payables-by-contact: Summarize money owed to suppliers.
• list-contact-groups: List defined groupings for contacts.

Write/Modification Operations:

• create-contact: Introduce a new client or supplier record.
• create-credit-note: Issue a new credit document.
• create-invoice: Draft a new bill to a customer.
• create-payment: Record a payment received or made.
• create-quote: Generate a new proposal for a client.
• create-payroll-timesheet: Submit a new record of hours worked (Payroll).
• update-contact: Modify details of an existing contact.
• update-invoice: Modify details of a pending draft invoice.
• update-quote: Modify details of a pending draft quotation.
• update-credit-note: Modify details of a pending draft credit note.
• update-payroll-timesheet-line: Adjust an entry within a timesheet (Payroll).
• approve-payroll-timesheet: Finalize and submit a timesheet for processing (Payroll).
• revert-payroll-timesheet: Undo the approval status of a timesheet (Payroll).
• add-payroll-timesheet-line: Append a new work entry line to a timesheet (Payroll).
• delete-payroll-timesheet: Remove an entire timesheet record (Payroll).
• get-payroll-timesheet: Fetch the full details of a specific timesheet record (Payroll).

For comprehensive documentation on request structures and expected responses, consult the official MCP Protocol Specification.

Developer Workflow

Local Dependency Installation

bash

Using npm

npm install

Using pnpm

pnpm install

Compilation Step

bash

Using npm

npm run build

Using pnpm

pnpm build

Connecting to Claude Desktop (Development)

To link this locally built Xero gateway within Claude Desktop's configuration (claude_desktop_config.json):

Windows Path Warning: Ensure that directory separators in the args array paths are properly escaped (e.g., "C:\path\to\server\dist\index.js").

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

Licensing Information

Distributed under the MIT License.

Security Posture

Sensitive material, including API keys and configuration secrets stored in .env, must never be committed to source control. The default .gitignore configuration already excludes this file for safety.