From 503d627dc85c7efc77a43b9ddef200a0fef489a0 Mon Sep 17 00:00:00 2001 From: "Eric G.Y Liu" Date: Mon, 28 Sep 2026 15:36:23 -0700 Subject: [PATCH] xero: add optional XERO_SCOPES setup field for Custom Connections created after 2026-04-29 (1.0.1) --- third_party/xero/.cursor-plugin/plugin.json | 7 ++++++- third_party/xero/CHANGELOG.md | 4 ++++ third_party/xero/README.md | 10 ++++++---- third_party/xero/mcp.json | 3 ++- 4 files changed, 18 insertions(+), 6 deletions(-) diff --git a/third_party/xero/.cursor-plugin/plugin.json b/third_party/xero/.cursor-plugin/plugin.json index 34a3a26db..cd6a348e8 100644 --- a/third_party/xero/.cursor-plugin/plugin.json +++ b/third_party/xero/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "xero", "displayName": "Xero", - "version": "1.0.0", + "version": "1.0.1", "minClientVersions": { "cursor": "3.13.0" }, @@ -42,6 +42,11 @@ "type": "string", "title": "Xero client secret", "description": "Client secret generated alongside the Custom Connection's client ID at developer.xero.com." + }, + "XERO_SCOPES": { + "type": "string", + "title": "Xero scopes (optional)", + "description": "Space-separated scopes granted to the Custom Connection, for example accounting.invoices accounting.contacts accounting.settings. Required for Custom Connections created on or after 2026-04-29; leave blank for older connections." } }, "required": [ diff --git a/third_party/xero/CHANGELOG.md b/third_party/xero/CHANGELOG.md index f94288d7b..dcc8ca380 100644 --- a/third_party/xero/CHANGELOG.md +++ b/third_party/xero/CHANGELOG.md @@ -2,6 +2,10 @@ All notable changes to this plugin will be documented here. +## 1.0.1 + +- Added an optional **Xero scopes** setup field, passed to the server as `XERO_SCOPES`. Custom Connections created on or after 2026-04-29 need it, because Xero rejects the server's default bundled-scope request for them with `invalid_client`. + ## 1.0.0 — initial release - Added the `xero` MCP server, running `@xeroapi/xero-mcp-server` locally over stdio. diff --git a/third_party/xero/README.md b/third_party/xero/README.md index 3e2ea49b4..539297da3 100644 --- a/third_party/xero/README.md +++ b/third_party/xero/README.md @@ -8,7 +8,7 @@ Read and write a Xero organisation's accounting and payroll data — invoices, c 1. Open **Cursor Settings → Plugins**. 2. Search for **Xero**. -3. Click **Install**, then set the Xero client ID and client secret (below). +3. Click **Install**, then set the Xero client ID, client secret and, for newer Custom Connections, scopes (below). Or run `/add-plugin xero` in chat. @@ -26,7 +26,8 @@ Or run `/add-plugin xero` in chat. ], "env": { "XERO_CLIENT_ID": "${XERO_CLIENT_ID}", - "XERO_CLIENT_SECRET": "${XERO_CLIENT_SECRET}" + "XERO_CLIENT_SECRET": "${XERO_CLIENT_SECRET}", + "XERO_SCOPES": "${XERO_SCOPES:-}" } } } @@ -38,9 +39,10 @@ Xero does not publish a hosted MCP endpoint. Its official server runs locally ov ## Before you connect 1. Sign in at [developer.xero.com](https://developer.xero.com) and create an app with the **Custom Connection** option. -2. Select the scopes up front. Connections created before 2026-04-29 use the bundled scope list; newer ones use the granular list. The server tries the bundled set first and falls back, so you usually do not need to set `XERO_SCOPES`. +2. Select the scopes up front. Connections created before 2026-04-29 use the bundled scope list; newer ones use the granular list. 3. Authorize the connection from the email Xero sends, and pick the organisation to connect. 4. Copy the **Client ID**, generate a **Client Secret**, and set both in **Dashboard → Plugins → Configure**. +5. For a connection created on or after 2026-04-29, also set **Xero scopes** to the space-separated granular scopes you selected, for example `accounting.invoices accounting.contacts accounting.settings`. Without it the server requests the bundled scopes, which Xero rejects for these connections with `invalid_client`. Leave it blank for older connections. A Custom Connection is bound to a single Xero organisation and is a paid add-on per organisation. Payroll tools require an NZ or UK organisation. @@ -62,7 +64,7 @@ The server is the source of truth for tool names and schemas. - This is a local stdio server, so `npx` has to be available on the machine running Cursor. It downloads `@xeroapi/xero-mcp-server` on first run. - Xero's own FAQ says the server works with any client supporting local stdio servers, and that its testing was done with Claude Desktop and Cursor. - Tool calls run with the scopes granted to the Custom Connection, against the one organisation it is bound to. To work with several organisations, create a connection per organisation. -- To narrow the surface further, add a space-separated `XERO_SCOPES` value to the server's `env` — for example `accounting.invoices accounting.contacts accounting.settings`. +- To narrow the surface on any connection, set **Xero scopes** to a subset of the connection's scopes. - `xero-mcp` by john-zhang-dev is a community package, and JAX is Xero's in-product assistant. Neither is this server. ## Docs diff --git a/third_party/xero/mcp.json b/third_party/xero/mcp.json index 52ba6ec03..dc24b9527 100644 --- a/third_party/xero/mcp.json +++ b/third_party/xero/mcp.json @@ -9,7 +9,8 @@ ], "env": { "XERO_CLIENT_ID": "${XERO_CLIENT_ID}", - "XERO_CLIENT_SECRET": "${XERO_CLIENT_SECRET}" + "XERO_CLIENT_SECRET": "${XERO_CLIENT_SECRET}", + "XERO_SCOPES": "${XERO_SCOPES:-}" } } }