Skip to main content
Glama
Sign In
xero-oauth-mcp-server

xero-oauth-mcp-server

by patthewebrat
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

xero-oauth-mcp-server

A custom Model Context Protocol server for Xero, using the standard OAuth2 authorization-code + refresh-token flow (no paid Custom Connection required). Supports multiple connected organisations (tenants) — every tool takes an optional org argument.

Capabilities

  • Contacts: list_contacts, get_contact, create_contact, update_contact

  • Invoices: list_invoices, get_invoice, get_invoice_pdf, download_invoice_pdfs, create_invoice, update_invoice, list_overdue_invoices, list_recurring_invoices

  • Utility: list_organisations, list_accounts

Related MCP server: Xero MCP Server

How org selection works

Each tool accepts an optional org. It is resolved (case-insensitive) against:

  1. an alias from XERO_ORG_ALIASES (e.g. main → a tenantId),

  2. an exact tenantId, then

  3. a substring of the org's name in Xero.

If org is omitted, the server uses XERO_DEFAULT_ORG (which may itself be an alias), or the first connected org when that is unset.

One-time setup

1. Create a Xero app

developer.xero.com → New app → Web app.

  • Add redirect URI: http://localhost:49831/callback

  • Copy the Client ID and generate a Client Secret.

Newer Xero apps use granular scopes. This server requests accounting.contacts, accounting.invoices, and accounting.settings.read (plus openid profile email offline_access). Make sure those are enabled on the app.

2. Build

npm install
npm run build

3. Authorize (interactive, once)

XERO_CLIENT_ID=xxx XERO_CLIENT_SECRET=yyy npm run auth

A browser opens — log in and authorize each organisation you want to use (re-run to add more later). The refresh token and the connected tenant list are saved to ~/.xero-mcp-id/tokens.json (chmod 600). The refresh token rotates automatically on every use.

4. Register with an MCP client

Example (Claude Code):

claude mcp add xero -s user \
  -e XERO_CLIENT_ID=xxx \
  -e XERO_CLIENT_SECRET=yyy \
  -e XERO_DEFAULT_ORG=main \
  -e XERO_ORG_ALIASES='{"main":"<tenant-guid>","secondary":"<tenant-guid>"}' \
  -- node /absolute/path/to/dist/index.js

Environment variables

Var

Default

Purpose

XERO_CLIENT_ID / XERO_CLIENT_SECRET

—

App credentials (required)

XERO_DEFAULT_ORG

first org

Org used when a tool omits org (alias/tenantId/name)

XERO_ORG_ALIASES

{}

JSON map of friendly alias → tenantId

XERO_REDIRECT_PORT

49831

Local callback port (must match the app's redirect URI)

XERO_PDF_DIR

~/Downloads

Where the PDF tools save files when no path is given

XERO_READONLY

unset

When true, all write tools refuse

XERO_TOKEN_DIR

~/.xero-mcp-id

Where the token store lives

Security

  • No credentials or tokens are stored in this repository.

  • Client ID/secret are passed via environment; the refresh token + tenant list live only in XERO_TOKEN_DIR (default ~/.xero-mcp-id/, chmod 600), which is git-ignored.

  • Write tools (create_* / update_*) can be globally disabled with XERO_READONLY=true.

License

MIT

Available Tools

12 tools
create_contactC

[WRITE] Create a new contact.

Inputs: name (required), org, firstName, lastName, +3 more.

create_invoiceB

[WRITE] Create an invoice (sales ACCREC by default). Defaults to DRAFT status.

Inputs: lineItems (required), org, type, contactId, +7 more.

get_contactA

Get a single contact by its contactID.

Inputs: contactId (required), org.

get_invoiceA

Get a single invoice (with line items) by invoiceID or invoice number.

Inputs: org, invoiceId, invoiceNumber.

list_accountsA

List the chart of accounts (codes, names, types, tax types) for an org — useful before creating invoices.

Inputs: org, where.

list_contactsB

List/search contacts in an org.

Inputs: org, searchTerm, where, page, +1 more.

list_invoicesC

List/search invoices in an org. Filter by status, contact, invoice number, or a raw Xero filter.

Inputs: org, statuses, contactIds, invoiceNumbers, +3 more.

list_organisationsA

List the connected Xero organisations (orgs) and the default one.

Inputs: no named parameters.

list_overdue_invoicesA

List overdue sales (ACCREC) invoices: AUTHORISED, past due date, with an outstanding balance.

Inputs: org, order.

list_recurring_invoicesC

List repeating (recurring) invoice templates in an org.

Inputs: org, where, order.

update_contactA

[WRITE] Update an existing contact (only supplied fields change).

Inputs: contactId (required), org, name, firstName, +5 more.

update_invoiceB

[WRITE] Update an invoice by invoiceID (e.g. change status, reference, due date, or line items).

Inputs: invoiceId (required), org, status, reference, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action (contact, invoice, accounts, etc.). Even specialized invoice tools like list_overdue_invoices and list_recurring_invoices have clear names that prevent ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (create_*, get_*, list_*, update_*), making it predictable and easy for an agent to infer purpose from the name.

    Tool Count5/5

    With 12 tools covering core CRUD for contacts and invoices plus useful listing filters, the set is well-scoped for a Xero accounting API server—neither too sparse nor too overwhelming.

    Completeness4/5

    Covers the main workflows for contacts and invoices (create, read, update, list) with additional filters. Missing delete operations and account creation/update, but these are often handled externally or are less critical for basic usage.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Xero Expenses MCP

      muness
      A
      license
      A
      quality
      D
      maintenance
      Enables interaction with Xero accounting software to create and manage invoices, bills, expenses, and expense claims with file attachments through PKCE authentication.
      21
      1
      MIT

    • Xero MCP Server

      WYRE-AI
      A
      license
      A
      quality
      B
      maintenance
      Enables interaction with the Xero Accounting API to manage contacts, invoices, payments, accounts, and financial reports. It provides a suite of tools for natural language access to accounting records and business performance data.
      20
      1
      Apache 2.0

    • Python Xero MCP Server for BYB

      BackyardBrains
      -
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Xero accounting API for financial reporting, sales analysis, grant tracking, and bill management using natural language.
      1
      -

    • xero-mcp-enhanced

      danielreddd
      A
      license
      Not graded
      quality
      D
      maintenance
      An enhanced MCP server for Xero, enabling natural language interaction with your Xero organisation for accounting tasks like invoices, contacts, bank transactions, and payroll.
      MIT