@xeroapi/xero-mcp-server

Registers Xero API endpoints as callable tools in MCP-compatible clients by exposing a schema-driven tool registry that maps Xero REST API operations to standardized MCP tool definitions. The server introspects Xero's API specification and generates tool schemas with parameter validation, enabling LLM agents to discover and invoke Xero operations (create invoice, fetch contacts, update accounts) without hardcoded integrations. Uses MCP's tool_call protocol to mediate between client requests and Xero API execution.

Manages Xero OAuth2 authentication lifecycle including initial authorization flow, access token storage, and automatic token refresh before expiration. The server implements the OAuth2 authorization code flow, stores refresh tokens securely (or via configurable persistence), and transparently refreshes expired tokens before API calls fail. Handles Xero's token expiration (typically 30 minutes) and refresh token rotation to maintain uninterrupted API access for long-running agent sessions.

Maps Xero REST API endpoints to callable tool operations with automatic parameter validation and type coercion. The server defines schemas for each Xero operation (e.g., CreateInvoice, GetContact, UpdateAccount) specifying required/optional parameters, data types, and constraints. Validates incoming tool_call requests against these schemas before forwarding to Xero, catching malformed requests early and providing clear error messages. Handles Xero-specific quirks like date formatting (YYYY-MM-DD), enum constraints (invoice status), and nested object structures.

Transforms Xero API responses into MCP-compatible tool_result format and handles Xero-specific error conditions. The server normalizes Xero's response structure (often nested with metadata), extracts relevant data fields, and formats results as JSON for the MCP client. Implements error handling for common Xero failures (401 Unauthorized, 429 Rate Limited, 400 Bad Request) with retry logic for transient errors and clear error messages for permanent failures. Maps Xero HTTP status codes to MCP error semantics.

Enables agents to execute multiple Xero API operations in sequence with optional transaction semantics (all-or-nothing execution). The server queues multiple tool_call requests, executes them in order, and can optionally rollback all operations if any step fails. Implements idempotency tracking to prevent duplicate operations if requests are retried. Useful for workflows like 'create invoice, add line items, mark as sent' that must succeed together or fail together.

Enables agents to traverse relationships between Xero entities (e.g., Invoice → Contact → Account) and automatically enrich responses with related data. The server implements lazy-loading or eager-loading strategies for related entities, reducing the number of API calls agents must make. For example, fetching an invoice can optionally include the associated contact details and account information in a single logical operation. Caches frequently accessed entities to reduce API calls.

Provides agents with filtering, sorting, and pagination capabilities for Xero queries that return large result sets (e.g., listing all contacts or invoices). The server translates agent-friendly filter syntax (e.g., 'invoices where status=DRAFT and date > 2024-01-01') into Xero's Odata query language. Implements cursor-based pagination to efficiently traverse large datasets without loading all results into memory. Supports sorting by multiple fields and complex filter expressions.