Xero MCP Server
A Model Context Protocol server that lets MCP clients (e.g., Claude) manage Xero accounting data — contacts, invoices, payments, chart of accounts, and financial reports.
Contacts: list (paginated, optional where clause), get by ID, create (customer/supplier), search by name
Invoices: list with status/type filters (ACCREC/ACCPAY), get details by ID (renders as an interactive read-only invoice card in MCP Apps hosts), create sales invoices or bills with line items, update status (submit/authorise/void)
Payments: list (paginated, filter by status), get by ID, create a payment against an invoice
Accounts: list chart of accounts (filter by type/class), get account details by ID
Reports: Profit & Loss (date range), Balance Sheet, Aged Receivables, Aged Payables
Discovery/help:
xero_navigateto explore tools by domain,xero_back, andxero_statusfor credential statusDeployment/auth: stdio, HTTP (HMAC
X-Gateway-S2Sverification), Docker/Compose, Cloudflare Workers; gateway mode for per-request multi-tenant credentials
Provides tools to manage Xero accounting resources including contacts, invoices, payments, and accounts, as well as generating financial reports such as Profit and Loss and Balance Sheets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Xero MCP Server Show me the profit and loss report for last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Xero MCP Server
Model Context Protocol (MCP) server for the Xero Accounting API. Enables Claude and other MCP-compatible clients to manage Xero contacts, invoices, payments, accounts, and reports.
Features
Contacts, invoices, payments, chart of accounts, and financial reports over stdio, HTTP, or Cloudflare Workers transports
Interactive invoice card (MCP Apps, SEP-1865):
xero_invoices_getrenders as a rich, read-only card in MCP Apps hosts — neutral by default, brandable viawindow.__BRAND__injection orMCP_BRAND_*env varsGateway mode for per-request, multi-tenant credentials
Related MCP server: Python Xero MCP Server for BYB
One-Click Deployment
Note on registry auth: This server depends only on public npm packages, so the Cloudflare and DigitalOcean cloud builders install its dependencies anonymously — no token is required for one-click deploy. (If a future release adds a private
@wyre-ai/*dependency, you would supply a GitHub PAT withread:packagesas a build variable —NODE_AUTH_TOKENfor Cloudflare Workers, a build-timeGITHUB_TOKENsecret for DigitalOcean.)Installing the published package: The released package is published to the GitHub Packages npm registry, which requires authentication on every install (even for public packages). To install it, authenticate npm to
npm.pkg.github.comwith a GitHub PAT that hasread:packages:export NODE_AUTH_TOKEN=$(gh auth token) npm install @wyre-ai/xero-mcp
Quick Start
Prerequisites
Node.js >= 20
Xero OAuth2 app credentials (requires a Xero developer account)
Install and Build
npm install
npm run buildRun (stdio mode)
XERO_ACCESS_TOKEN=your-access-token XERO_TENANT_ID=your-tenant-id npm startRun (HTTP mode)
CONDUIT_S2S_SECRET is required. If it is empty or a known placeholder, the process logs an error and exits non-zero. It never prints the secret.
MCP_TRANSPORT=http \
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
XERO_ACCESS_TOKEN=your-access-token \
XERO_TENANT_ID=your-tenant-id \
npm startWith a secret set and MCP_HTTP_HOST unset, the server listens on http://0.0.0.0:8080/mcp.
Local HTTP without a secret is development-only. It logs a warning, does not check X-Gateway-S2S, and binds 127.0.0.1 only (a non-loopback MCP_HTTP_HOST is ignored):
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm startDocker
The image listens on 0.0.0.0 inside the container. Publish the port on loopback and pass the S2S secret. Gateway mode does not read Xero credentials from the environment:
docker build -t xero-mcp .
docker run \
-e CONDUIT_S2S_SECRET=your-s2s-secret \
-e AUTH_MODE=gateway \
-p 127.0.0.1:8080:8080 \
xero-mcpSingle-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses XERO_ACCESS_TOKEN and XERO_TENANT_ID:
docker run \
-e CONDUIT_S2S_SECRET=your-s2s-secret \
-e AUTH_MODE=env \
-e XERO_ACCESS_TOKEN=your-access-token \
-e XERO_TENANT_ID=your-tenant-id \
-p 127.0.0.1:8080:8080 \
xero-mcpDocker Compose
The checked-in Compose service is gateway mode. It does not set XERO_ACCESS_TOKEN or XERO_TENANT_ID and does not use env_file, so a project .env cannot inject static vendor credentials into the container. Compose refuses to start when CONDUIT_S2S_SECRET is unset or empty, and publishes 127.0.0.1:8080:8080.
CONDUIT_S2S_SECRET=your-s2s-secret docker compose upEnvironment Variables
Copy .env.example. Leave CONDUIT_S2S_SECRET empty in that file.
Variable | Required | Default | Description |
| For stdio and | — | Xero OAuth2 access token. Not set on the gateway Compose service. |
| For stdio and | — | Xero tenant ID (organisation). Not set on the gateway Compose service. |
| No |
| Transport type: |
| No |
| HTTP server port |
| No |
| Bind address. A configured secret honors this value. With no secret, |
| No |
|
|
| Yes for HTTP | — | Service-to-service HMAC secret. HTTP startup exits non-zero when this is empty or a known placeholder. Never commit a real value. The value is never logged. |
| No | unset | Set to exactly |
/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
HTTP authentication
With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts.
The header value is t=<unix seconds>,v1=<hex>:
<unix seconds>is the current UTC time.<hex>is HMAC-SHA256 of the literal stringt=<unix seconds>(the samet=prefix and digits), keyed withCONDUIT_S2S_SECRET, encoded as 64 lowercase hex characters.The timestamp must be within 300 seconds of the server clock.
A missing or invalid header is HTTP 401, before vendor credentials are read. The secret is never logged.
TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
-H "X-Xero-Access-Token: $XERO_ACCESS_TOKEN" \
-H "X-Xero-Tenant-Id: $XERO_TENANT_ID" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Known placeholders (replace-with-a-real-secret, your-s2s-secret, your-secret, changeme, change-me, placeholder, secret, example, replace-me, s2s-secret, any case, surrounding whitespace ignored) are refused at startup so a copied example cannot forge that header. Generate a secret with openssl rand -hex 32.
Gateway Mode
When AUTH_MODE=gateway, credentials are passed per-request via HTTP headers instead of environment variables:
X-Xero-Access-Token— OAuth2 access tokenX-Xero-Tenant-Id— Xero tenant ID
A request missing either header gets HTTP 401 and does not fall back to XERO_ACCESS_TOKEN or XERO_TENANT_ID. When CONDUIT_S2S_SECRET is set, the request must also include a valid X-Gateway-S2S header. This allows a gateway/proxy to manage multi-tenant credentials.
Interactive Invoice Card (MCP Apps)
xero_invoices_get renders as an interactive card in MCP Apps hosts
(Claude Desktop/web) showing status, contact, dates, amounts, and line
items; plain-JSON behavior is unchanged in other hosts. The card is
read-only — invoices are financial records, so no write actions are
exposed from it. It is neutral by default and brandable via
window.__BRAND__ injection or MCP_BRAND_* env vars (MCP_BRAND_NAME,
MCP_BRAND_LOGO_URL, MCP_BRAND_PRIMARY_COLOR, MCP_BRAND_ACCENT_COLOR,
MCP_BRAND_BG, MCP_BRAND_TEXT) — no rebuild needed.
Available Tools
Tools are organized into domains. Use xero_navigate to select a domain, then use the domain-specific tools.
Navigation
xero_navigate— Select a domain (contacts, invoices, payments, accounts, reports)xero_back— Return to domain selection
Contacts
xero_contacts_list— List contacts with pagination and optional filteringxero_contacts_get— Get detailed contact information by IDxero_contacts_create— Create a new contact (customer or supplier)xero_contacts_search— Search contacts by name
Invoices
xero_invoices_list— List invoices with optional status and type filtersxero_invoices_get— Get detailed invoice information by IDxero_invoices_create— Create a new invoice (sales or bill)xero_invoices_update_status— Update invoice status (submit, authorise, void)
Payments
xero_payments_list— List payments with optional status filterxero_payments_get— Get detailed payment information by IDxero_payments_create— Record a payment against an invoice
Accounts
xero_accounts_list— List chart of accounts with optional type/class filterxero_accounts_get— Get detailed account information by ID
Reports
xero_reports_profit_and_loss— Profit and Loss (income statement) for a date rangexero_reports_balance_sheet— Balance Sheet as of a specific datexero_reports_aged_receivables— Aged Receivables by contactxero_reports_aged_payables— Aged Payables by contact
License
Apache-2.0
Available Tools
20 toolsxero_accounts_getA
Get detailed information about a specific account by its ID.
Inputs: accountId (required).
xero_accounts_listB
List chart of accounts in Xero. Optionally filter by account type or class.
Inputs: Type, Class.
xero_backA
Return to domain selection (no-op in flattened mode). All tools are always available.
Inputs: no named parameters.
xero_contacts_createB
Create a new contact in Xero. Name is required; other fields are optional.
Inputs: Name (required), Phone, LastName, FirstName, +5 more.
xero_contacts_getA
Get detailed information about a specific contact by its ID. Returns full contact profile including addresses, phone numbers, and email.
Inputs: contactId (required).
xero_contacts_listA
List contacts in Xero with pagination. Optionally filter using a where clause. Returns contact details including name, email, and addresses.
Inputs: page, where.
xero_contacts_searchA
Search contacts by name. Returns contacts whose name contains the search term.
Inputs: term (required).
xero_invoices_createB
Create a new invoice in Xero. Requires type, contact, and at least one line item.
Inputs: Type (required), ContactID (required), LineItems (required), Date, +3 more.
xero_invoices_getA
Get detailed information about a specific invoice by its ID. Returns full invoice details including line items, amounts, and payment status.
Inputs: invoiceId (required).
xero_invoices_listA
List invoices in Xero with pagination. Optionally filter by status and type (ACCREC for sales, ACCPAY for bills).
Inputs: Type, page, Status.
xero_invoices_update_statusA
Update the status of an existing invoice. Can submit, authorise, or void an invoice.
Inputs: Status (required), invoiceId (required).
xero_payments_createB
Create a new payment in Xero. Records a payment against an invoice.
Inputs: Date (required), Amount (required), AccountID (required), InvoiceID (required), +1 more.
xero_payments_getA
Get detailed information about a specific payment by its ID.
Inputs: paymentId (required).
xero_payments_listA
List payments in Xero with pagination. Optionally filter by status.
Inputs: page, Status.
xero_reports_aged_payablesA
Get an Aged Payables report showing outstanding supplier bills by age.
Inputs: date (required).
xero_reports_aged_receivablesA
Get an Aged Receivables report showing outstanding customer invoices by age.
Inputs: date (required).
xero_reports_balance_sheetB
Get a Balance Sheet report as of a specific date.
Inputs: date (required).
xero_reports_profit_and_lossA
Get a Profit and Loss (income statement) report for a date range.
Inputs: toDate (required), fromDate (required).
xero_statusA
Show credentials status and available domains
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools are clearly distinct by resource and action. The main ambiguity is between xero_contacts_list and xero_contacts_search, and the three navigation/utility tools (xero_navigate, xero_status, xero_back) add some conceptual overlap, though their roles are explained.
Tool names follow a very consistent xero_<domain>_<action> pattern throughout, with predictable verbs like list, get, create, and update_status. Even the report tools use clear domain-action naming with full report names.
At 20 tools, the server is in the heavier range, especially because xero_navigate, xero_status, and xero_back are meta/navigation aids that do not add domain functionality in a flattened mode. The 17 domain tools are mostly justified, but the overall surface feels a bit bloated.
Core accounting workflows are covered—contacts, invoices, payments, accounts, and key reports—but the surface has notable lifecycle gaps. Contacts and invoices lack update/delete operations, accounts are read-only, and payments have no update or reversal capability.
Maintenance
Related MCP Connectors
Query and export Xero finance data and prepare accounting drafts in your xpnAI Workspace.
Connect Xero to AI agents with secure read or write access across multiple organisations.
Accounts receivable automation for Xero and QuickBooks Online, inside your AI assistant. Ask Claude, ChatGPT or any MCP client for a receivables summary, find customers and invoices, read the email and SMS replies your customers sent, and see what Paidnice sent or skipped. Ask why a reminder, late fee or statement did or did not go out, and update a customer's contact people straight into your ledger. Secure OAuth sign-in. One connection covers every organisation you tick, with Read or Read and Write access.
Malaysian SME accounting, e-Invoice and payroll for your AI. 95 tools; writes are approved drafts.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to interact with QuickFile UK accounting software, providing access to invoicing, client management, purchases, banking, and financial reporting through 40+ tools covering the complete QuickFile API.8 npm4MIT
- -licenseNot gradedqualityDmaintenanceEnables interaction with Xero accounting API for financial reporting, sales analysis, grant tracking, and bill management using natural language.1-
- AlicenseAqualityCmaintenanceEnables natural language interaction with Xero accounting data, managing contacts, invoices, and accounts across multiple organisations via OAuth2.12MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to query and manage self-hosted accounting data—invoices, balances, and books—through natural language, with read-only tools by default and optional scoped write operations.3027 PyPI1AGPL 3.0