Xero MCP Server

https://github.com/xeroapi/xero-mcp-server
Admin
A Model Context Protocol (MCP) server implementation for Xero, providing a bridge to Xero's API for...
Tokens:35,203
Snippets:231
Trust Score:7.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Basic usage with xeroClient

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-client.md

Basic usage example: imports the xeroClient, authenticates to fetch a token and tenantId, then calls getAccounts with the tenantId and client headers.

```ts
import { xeroClient } from "./src/clients/xero-client.js";

await xeroClient.authenticate(); // fetches a token + tenantId

const accounts = await xeroClient.accountingApi.getAccounts(
  xeroClient.tenantId,
  undefined, undefined, undefined, getClientHeaders(),
);
```

--------------------------------

### Install OpenAI agents SDK

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/examples/openai-agents/README.md

Install the OpenAI agents SDK using pip.

```bash
pip install openai-agents
```

--------------------------------

### Example: getClientHeaders usage

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/helpers.md

Shows an example of calling getClientHeaders to get a user-agent header with the package version.

```TypeScript
const ua = getClientHeaders(); // { headers: { "user-agent": "xero-mcp-server-0.0.16" } }
```

--------------------------------

### Create contact example

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/tools-create.md

Example of calling createXeroContact with a name, email, and phone. The result is checked for errors, and on success the contact name and ID are logged.

```typescript
const res = await createXeroContact("Acme Pty Ltd", "billing@acme.example", "0400 000 000");
if (res.isError) {
  console.error(res.error); // e.g. "Authentication failed. Please check your Xero credentials."
} else {
  console.log(res.result.name, res.result.contactID);
}
```

--------------------------------

### Install dependencies with npm or pnpm

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/README.md

Install project dependencies using either npm or pnpm. Choose the command that matches your package manager.

```bash
# Using npm
npm install

# Using pnpm
pnpm install
```

--------------------------------

### Error handling at startup

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-mcp-server.md

Example of error handling at startup, mirroring index.ts behavior. It checks that GetServer() returns an instance, writes 'ready' to stdout, and logs errors to stderr before exiting with code 1.

```ts
import { XeroMcpServer } from "./src/server/xero-mcp-server.js";

try {
  const server = XeroMcpServer.GetServer();
  if (!server) throw new Error("GetServer returned no instance");
  process.stdout.write("ready");
} catch (error) {
  console.error("Error:", error); // mirrors index.ts behavior
  process.exit(1);
}
```

--------------------------------

### .env.example for Custom Connections

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/configuration.md

Example .env file for Custom Connections authentication. Replace the placeholder values with your actual Xero client ID and secret. This file is loaded by dotenv.config() from the working directory if present.

```plaintext
# Xero API Configuration for Custom Connections
XERO_CLIENT_ID=your_client_id_here
XERO_CLIENT_SECRET=your_client_secret_here
```

--------------------------------

### CreateXeroTool usage example

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/helpers.md

Example of using CreateXeroTool to define a tool named 'list-accounts'. The handler calls listXeroAccounts and returns an error message in the tool result.

```TypeScript
const ListAccountsTool = CreateXeroTool(
  "list-accounts",
  "Lists all accounts in Xero...",
  {}, // no args
  async () => {
    const response = await listXeroAccounts();
    return {
      content: [{ type: "text" as const, text: `Error listing accounts: ${response.error}` }],
    };
  },
);
```

--------------------------------

### Consuming the server programmatically

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-mcp-server.md

Example of consuming the singleton programmatically to register custom tools before server.connect() is called. Note that GetServer() returns the same instance every time.

```ts
import { XeroMcpServer } from "./src/server/xero-mcp-server.js";

const server = XeroMcpServer.GetServer();
// ToolFactory(server) has already run in index.ts; register custom tools here
console.log(server); // McpServer instance
```

--------------------------------

### Create invoice using createXeroInvoice

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/tools-create.md

TypeScript example that creates an ACCREC invoice with a line item, reference, and date. The result is checked for errors before logging the invoice ID and total.

```TypeScript
const res = await createXeroInvoice(
  contactId,
  [{ description: "Widget", quantity: 2, unitAmount: 10, accountCode: "200", taxType: "OUTPUT" }],
  Invoice.TypeEnum.ACCREC,
  "INV-REF-1",
  "2025-01-15",
);
if (res.isError) console.error(res.error);
else console.log(res.result.invoiceID, res.result.total);
```

--------------------------------

### Example usage of formatError

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/helpers.md

Shows how to call formatError in a try/catch block when using the Xero accounting API. The comment indicates the expected output for a 401 error.

```TypeScript
try {
  await xeroClient.accountingApi.getAccounts(...);
} catch (error) {
  const message = formatError(error); // "Authentication failed. Please check your Xero credentials."
}
```

--------------------------------

### Error handling with formatError

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-client.md

Error handling example: wraps authentication and getShortCode in a try/catch, logging the formatted error via formatError. Token acquisition failures surface as thrown Errors or rejections.

```ts
import { xeroClient } from "./src/clients/xero-client.js";
import { formatError } from "./src/helpers/format-error.js";

try {
  await xeroClient.authenticate();
  const org = await xeroClient.getShortCode();
  console.log(org); // cached short code or undefined
} catch (error) {
  // e.g. Error("Failed to get Xero token with V1 scopes: ...")
  console.error(formatError(error));
}
```

--------------------------------

### CreateTools registry array in create/index.ts

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/tool-factory.md

Example of a registry array holding tool factory thunks. Each array is of type ToolList (ReturnType<typeof CreateXeroTool>[]). This array lists the 11 create tools.

```TypeScript
export const CreateTools = [
  CreateContactTool,
  CreateCreditNoteTool,
  CreateManualJournalTool,
  CreateInvoiceTool,
  CreateQuoteTool,
  CreatePaymentTool,
  CreateItemTool,
  CreateBankTransactionTool,
  CreatePayrollTimesheetTool,
  CreateTrackingCategoryTool,
  CreateTrackingOptionsTool
];
```

--------------------------------

### Build project with npm or pnpm

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/README.md

Build the project using either npm or pnpm. Use the command that matches your package manager.

```bash
# Using npm
npm run build

# Using pnpm
pnpm build
```

--------------------------------

### ensureError usage example

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/helpers.md

Example usage of ensureError, showing that it always returns an Error instance.

```TypeScript
const err = ensureError(unknownThrownValue); // always an Error instance
```

--------------------------------

### Process bootstrap (src/index.ts)

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-mcp-server.md

Process bootstrap from src/index.ts, the bin target. It creates the singleton server, registers all tools via ToolFactory, connects to StdioServerTransport, and exits with code 1 on error.

```ts
#!/usr/bin/env node

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { XeroMcpServer } from "./server/xero-mcp-server.js";
import { ToolFactory } from "./tools/tool-factory.js";

const main = async () => {
  // Create an MCP server
  const server = XeroMcpServer.GetServer();

  ToolFactory(server);

  // Start receiving messages on stdin and sending messages on stdout
  const transport = new StdioServerTransport();
  await server.connect(transport);
};

main().catch((error) => {
  console.error("Error:", error);
  process.exit(1);
});
```

--------------------------------

### Configure Xero MCP server for Claude Desktop

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/README.md

Add this configuration to your claude_desktop_config.json file to link the Xero MCP server to Claude Desktop. For Windows, ensure the args path escapes backslashes between folders, e.g., "C:\\projects\xero-mcp-server\dist\index.js". Replace the placeholder file path and environment variables with your actual values.

```json
{
  "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"
      }
    }
  }
}
```

--------------------------------

### CustomConnectionsXeroClient

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-client.md

Documentation for the CustomConnectionsXeroClient class, including its constructor, default scopes, and methods for obtaining client credentials tokens and authenticating.

```APIDOC
## CustomConnectionsXeroClient

### Description
Client for Xero **Custom Connections** (client credentials OAuth2 flow). Uses `axios` directly against `https://identity.xero.com/connect/token` with HTTP Basic authentication (`clientId:clientSecret` base64).

### Constructor

```ts
constructor(config: {
  clientId: string;
  clientSecret: string;
  grantType: string;
}) {
  super(config);
  this.clientId = config.clientId;
  this.clientSecret = config.clientSecret;
}
```

`super(config)` passes the whole config object to the `XeroClient` SDK constructor (i.e. `IXeroClientConfig` fields plus the custom ones).

### Default scopes

| Constant | Line | Scopes |
|----------|------|--------|
| `XERO_DEFAULT_AUTH_SCOPES_V1` (`src/clients/xero-client.ts:82-90`) | Legacy | `accounting.transactions accounting.contacts accounting.settings accounting.reports.read payroll.settings payroll.employees payroll.timesheets` |
| `XERO_DEFAULT_AUTH_SCOPES_V2` (`src/clients/xero-client.ts:93-112`) | Granular | `accounting.invoices accounting.payments accounting.banktransactions accounting.manualjournals accounting.reports.aged.read accounting.reports.balancesheet.read accounting.reports.profitandloss.read accounting.reports.trialbalance.read accounting.contacts accounting.settings payroll.settings payroll.employees payroll.timesheets` |

### `getClientCredentialsToken(): Promise<TokenSet>`

1. If `process.env.XERO_SCOPES` is set, calls `requestToken(XERO_SCOPES)`; on failure throws `formatTokenError(error, " with XERO_SCOPES"`.
2. Otherwise tries V1 scopes first (`requestToken(XERO_DEFAULT_AUTH_SCOPES_V1)`); on `400` with body `error === "invalid_scope"` falls back to `requestToken(XERO_DEFAULT_AUTH_SCOPES_V2)`; any other failure throws `formatTokenError(error, " with V1 scopes")`; V2 failure throws with `" with V2 scopes"`.
3. Token errors are formatted as `Error("Failed to get Xero token<context>: <message>")` where the message is `JSON.stringify(response.data)` when present, else `axiosError.message`.

### `requestToken(scope: string): Promise<TokenSet>`

`POST https://identity.xero.com/connect/token` with body `grant_type=client_credentials&scope=<encodeURIComponent(scope)>`, headers `Authorization: Basic <base64(clientId:clientSecret)>`, `Content-Type: application/x-www-form-urlencoded`, `Accept: application/json`. Then `GET https://api.xero.com/connections` with `Authorization: Bearer <access_token>`; if any connections are returned, sets `this.tenantId = connectionsResponse.data[0].tenantId`. Returns `response.data`.

### `authenticate(): Promise<void>` (declared `public async authenticate()`)

Calls `getClientCredentialsToken()` then `this.setTokenSet({ access_token, expires_in, token_type })`.
```

--------------------------------

### Configuration resolution and validation

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-client.md

Loads environment variables and validates that either a bearer token or both client ID and secret are present. Throws an error at import time if the required variables are missing, which aborts server startup.

```typescript
dotenv.config();

const client_id = process.env.XERO_CLIENT_ID;
const client_secret = process.env.XERO_CLIENT_SECRET;
const bearer_token = process.env.XERO_CLIENT_BEARER_TOKEN;
const grant_type = "client_credentials";

if (!bearer_token && (!client_id || !client_secret)) {
  throw Error("Environment Variables not set - please check your .env file");
}
```

--------------------------------

### Registering a custom tool alongside built-ins

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/tool-factory.md

Shows how to register a custom tool using CreateXeroTool and server.tool after calling ToolFactory. The custom tool returns a text response 'pong' when invoked.

```TypeScript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { XeroMcpServer } from "./src/server/xero-mcp-server.js";
import { ToolFactory } from "./src/tools/tool-factory.js";
import { CreateXeroTool } from "./src/helpers/create-xero-tool.js";

const server: McpServer = XeroMcpServer.GetServer();
ToolFactory(server); // registers all built-in tools

const PingTool = CreateXeroTool("ping", "Ping the server", {}, async () => ({
  content: [{ type: "text" as const, text: "pong" }],
}));

const def = PingTool();
server.tool(def.name, def.description, def.schema, def.handler);
```

--------------------------------

### ToolFactory function in tool-factory.ts

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/tool-factory.md

Registers all tools from the registry arrays with the MCP server. Each registry array holds tool factory thunks; calling tool() evaluates the thunk to a ToolDefinition, then server.tool() registers it. Registration order is Delete, Get, Create, List, Update. No de-duplication check is performed.

```TypeScript
export function ToolFactory(server: McpServer) {

  DeleteTools.map((tool) => tool()).forEach((tool) =>
    server.tool(tool.name, tool.description, tool.schema, tool.handler),
  );
  GetTools.map((tool) => tool()).forEach((tool) =>
    server.tool(tool.name, tool.description, tool.schema, tool.handler),
  );
  CreateTools.map((tool) => tool()).forEach((tool) =>
    server.tool(tool.name, tool.description, tool.schema, tool.handler),
  );
  ListTools.map((tool) => tool()).forEach((tool) =>
    server.tool(tool.name, tool.description, tool.schema, tool.handler),
  );
  UpdateTools.map((tool) => tool()).forEach((tool) =>
    server.tool(tool.name, tool.description, tool.schema, tool.handler),
  );
}
```

--------------------------------

### Response shape for tools/call

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/endpoints.md

Every Xero MCP tool handler returns this exact content structure. On success, `text` contains a human-readable summary; on failure, it starts with `Error <operation>: ` followed by the mapped error string. Report tools additionally include JSON-formatted report rows.

```TypeScript
{
  content: [
    {
      type: "text",
      text: "<formatted result, or `Error <context>: <error string>` on failure>",
    },
  ],
}
```

--------------------------------

### Set environment variables for Xero and OpenAI

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/examples/openai-agents/README.md

Export the required environment variables: XERO_CLIENT_ID, XERO_CLIENT_SECRET, and OPENAI_API_KEY.

```bash
export XERO_CLIENT_ID=your_xero_client_id
export XERO_CLIENT_SECRET=your_xero_client_secret
export OPENAI_API_KEY=your_openai_api_key
```

--------------------------------

### MCPXeroClient abstract class definition

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-client.md

Defines the abstract MCPXeroClient class extending XeroClient. It includes a tenantId field, a private shortCode field, a constructor, an abstract authenticate() method, an overridden updateTenants() method, and a private getOrganisation() method. The getShortCode() method lazily fetches and caches the organisation short code, throwing an error if retrieval fails.

```TypeScript
abstract class MCPXeroClient extends XeroClient {
  public tenantId: string;
  private shortCode: string;

  protected constructor(config?: IXeroClientConfig) {
    super(config);
    this.tenantId = "";
    this.shortCode = "";
  }

  public abstract authenticate(): Promise<void>;

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  override async updateTenants(fullOrgDetails?: boolean): Promise<any[]> {
    await super.updateTenants(fullOrgDetails);
    if (this.tenants && this.tenants.length > 0) {
      this.tenantId = this.tenants[0].tenantId;
    }
    return this.tenants;
  }

  private async getOrganisation(): Promise<Organisation> {
    await this.authenticate();

    const organisationResponse = await this.accountingApi.getOrganisations(
      this.tenantId || "",
    );

    return organisationResponse.body.organisations?.[0];
  }

  public async getShortCode(): Promise<string | undefined> {
    if (!this.shortCode) {
      try {
        const organisation = await this.getOrganisation();
        this.shortCode = organisation.shortCode ?? "";
      } catch (error: unknown) {
        const err = ensureError(error);

        throw new Error(
          `Failed to get Organisation short code: ${err.message}`,
        );
      }
    }
    return this.shortCode;
  }
}
```

--------------------------------

### list-trial-balance

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/tools-list.md

Returns a trial balance (general ledger snapshot). Accepts optional date and paymentsOnly parameters. Returns report name, date, updated-at, and stringified report rows.

```APIDOC
## list-trial-balance

### Description
Trial balance (general ledger snapshot).

### Input
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `date` | `string` | no | Date `YYYY-MM-DD` |
| `paymentsOnly` | `boolean` | no | Only accounts with payments |

### Handler
`listXeroTrialBalance(date?, paymentsOnly?)`

### Output
Report name, date, updated-at, `JSON.stringify(report.rows, null, 2)`.
```

--------------------------------

### BearerTokenXeroClient class for BYO token

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-client.md

Defines the BearerTokenXeroClient class for Bring-Your-Own-Token mode. The constructor stores the bearer token, and authenticate() sets it as the access token and immediately discovers tenants.

```ts
class BearerTokenXeroClient extends MCPXeroClient {
  private readonly bearerToken: string;

  constructor(config: { bearerToken: string }) {
    super();
    this.bearerToken = config.bearerToken;
  }

  async authenticate(): Promise<void> {
    this.setTokenSet({
      access_token: this.bearerToken,
    });

    await this.updateTenants();
  }
}
```

--------------------------------

### XeroMcpServer class signature

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/api-reference/xero-mcp-server.md

Class signature for XeroMcpServer, a stateless singleton factory that lazily constructs and returns a single McpServer instance. The private constructor prevents direct instantiation, and GetServer() returns the cached instance if it exists.

```ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export class XeroMcpServer {
  private static instance: McpServer | null = null;

  private constructor() {}

  public static GetServer(): McpServer {
    if (XeroMcpServer.instance === null) {
      XeroMcpServer.instance = new McpServer({
        name: "Xero MCP Server",
        version: "1.0.0",
      });
    }
    return XeroMcpServer.instance;
  }
}
```

--------------------------------

### Claude Desktop config for Custom Connections

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/_autodocs/configuration.md

Claude Desktop configuration for Custom Connections mode. Sets the XERO_CLIENT_ID, XERO_CLIENT_SECRET, and optionally XERO_SCOPES environment variables. The server runs via npx with the @xeroapi/xero-mcp-server package.

```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",
        "XERO_SCOPES": "accounting.invoices accounting.contacts accounting.settings"
      }
    }
  }
}
```

--------------------------------

### Claude Desktop config for Xero MCP server with bearer token

Source: https://github.com/xeroapi/xero-mcp-server/blob/main/README.md

Configuration for Claude Desktop to use the Xero MCP server with a bearer token, suitable for supporting multiple Xero accounts at runtime. The XERO_CLIENT_BEARER_TOKEN takes precedence over XERO_CLIENT_ID if both are defined.

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