MCP Ecommerce

Installation guide

How to install Xero MCP Server

In Claude, ChatGPT, Gemini, Microsoft Copilot, Perplexity, Cursor and Claude Code, with what to check before you start and the first prompts to run.

The Xero MCP Server is an open-source (MIT) server maintained by Xero that runs on your own machine. Your MCP client launches it with `npx -y @xeroapi/xero-mcp-server@latest` and authenticates to Xero with Custom Connection credentials (`XERO_CLIENT_ID` and `XERO_CLIENT_SECRET`) or a bearer token (`XERO_CLIENT_BEARER_TOKEN`). There is no hosted URL, so only clients that can start a local command are a natural fit.

This is best done by a developer or finance systems owner who can create a Custom Connection in the Xero developer portal and who has access to the target Xero organisation. Start with a Xero Demo Company, not a live organisation. The server exposes write tools (invoices, payments, manual journals, payroll timesheets), so scope credentials tightly and keep the first sessions read-only.

Xero MCP Server setup guide: Xero's MCP documentation page on github.com, shown in a browser frame (payments MCP server for e-commerce)
Xero MCP Server setup guide preview: Xero’s documentation on github.com, captured Oct 13, 2026. The page may have changed since; the link opens the live version.

Before you start

  • Node.js v18 or higher, and npm or pnpm, installed on the machine running the client.
  • A Xero developer account with API credentials, and a Xero Demo Company to test against (Payroll queries need an NZ or UK region).
  • A Custom Connection created per the Xero Custom Connections guide, with every scope from SCOPES_V1 (created before Apr 29, 2026) or SCOPES_V2 (created from that date) added. The documentation says the server tries V1 first and falls back to V2.
  • Your XERO_CLIENT_ID and XERO_CLIENT_SECRET, or a bearer token if your client runs its own auth flow such as PKCE.
  • If you use Node Version Manager, the full path to your npx executable.
How it runs
Local, runs on your machine
Access
Read and write
Server address
Copy it from the vendor documentation

Xero MCP Server in Claude

  1. Create the Custom Connection in the Xero developer portal and note the client ID and secret.
  2. In Claude Desktop, open Settings > Developer > Edit config to open claude_desktop_config.json.
  3. Add the xero entry from the snippet under mcpServers, replacing the placeholder client ID and secret.
  4. Optionally set XERO_SCOPES to a space-separated list of scopes to narrow permissions. If omitted, the default scopes are used.
  5. If you use Node Version Manager, replace npx in command with the full path to the executable, for example your_home_directory/.nvm/versions/node/v22.14.0/bin/npx on Mac or Linux.
  6. Save the file, fully restart Claude Desktop, and confirm the xero server is listed. This is a local server, so the web Claude.ai connector by URL does not apply.
claude_desktop_config.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 MCP Server in ChatGPT

  1. The Xero documentation does not cover ChatGPT. This server runs locally over a command, and ChatGPT Developer mode custom connectors expect a remote MCP server URL.
  2. The documentation provides no hosted endpoint, so do not guess a URL.
  3. If you need ChatGPT access, check the vendor repository at https://github.com/XeroAPI/xero-mcp-server for a hosted option or an example. The repo includes an examples/openai-agents folder for the OpenAI Agents SDK.
  4. Otherwise use a client that can launch a local command, such as Claude Desktop, Cursor or Claude Code.

Xero MCP Server in Gemini

  1. The Xero documentation does not cover Gemini. Use Gemini CLI's standard way of adding a local server: an entry under mcpServers in its settings JSON.
  2. Open your Gemini CLI settings file and add a xero entry using the command and args from the snippet, with your Custom Connection credentials in env.
  3. If you use Node Version Manager, replace npx with its full path, as the Xero documentation describes for Claude Desktop.
  4. Restart Gemini CLI and check that the server and its tools are listed.
  5. Run a read-only request against the Demo Company first.
Gemini CLI settings (mcpServers)
{
  "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 MCP Server in Microsoft Copilot

  1. The Xero documentation does not cover Microsoft Copilot Studio or GitHub Copilot. For GitHub Copilot in VS Code, use the standard .vscode/mcp.json file with a top-level servers object.
  2. Add a xero server with command set to npx and the same args as the snippet, and your credentials in env.
  3. Prefer VS Code input variables or environment variables over committing the client secret. The vendor says not to commit credentials to version control.
  4. Start the server from the MCP controls in VS Code and confirm the tools appear in Copilot Chat in agent mode.
  5. Copilot Studio expects a remote MCP endpoint, which the documentation does not provide for this server.
.vscode/mcp.json
{
  "servers": {
    "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 MCP Server in Perplexity

  1. The Xero documentation does not cover Perplexity.
  2. In the Perplexity desktop app, open the connectors settings and look for the option to add a custom or local MCP server. Availability depends on your version and plan.
  3. If a local command option exists, use npx with the args -y and @xeroapi/xero-mcp-server@latest, and set XERO_CLIENT_ID and XERO_CLIENT_SECRET as environment variables.
  4. Because the server has no hosted URL, a URL-only connector option will not work.
  5. Confirm with a read-only request against the Demo Company.

Xero MCP Server in Cursor

  1. Open Cursor's MCP settings and choose to add a new MCP server. This opens mcp.json. The Xero documentation does not cover Cursor, so this uses the standard format.
  2. Add the xero entry from the snippet under mcpServers.
  3. Replace the placeholder client ID and secret with your Custom Connection values. Optionally set XERO_SCOPES to narrow permissions.
  4. If you use Node Version Manager, replace npx with its full path.
  5. Reload Cursor, enable the xero server in the MCP settings, and check that its tools are listed.
mcp.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 MCP Server in Claude Code

  1. The Xero documentation does not show a Claude Code command. This uses the standard claude mcp add form for a local server, with the package and variables from the docs.
  2. Run the command in the snippet in your terminal, replacing the placeholder credentials. The -e flag sets environment variables.
  3. If you use Node Version Manager, replace npx with its full path.
  4. Run claude mcp list to confirm xero is registered, then start claude and check /mcp.
  5. If your own auth flow supplies a token, set XERO_CLIENT_BEARER_TOKEN instead of the client ID and secret. It takes precedence over the client ID.
Terminal
claude mcp add xero -e XERO_CLIENT_ID=your_client_id_here -e XERO_CLIENT_SECRET=your_client_secret_here -- npx -y @xeroapi/xero-mcp-server@latest

Check that it works

Start with questions that only read data. If these answer from your real account, the connection is good.

  • Using the Xero Demo Company, list organisation details and confirm the organisation name matches the Demo Company.
  • List the 10 most recent invoices from Xero and summarise their status and totals. Do not create or change anything.
  • Retrieve the profit and loss report for the last full month from Xero, read-only.

Troubleshooting

+The client does not list the xero server or fails to start it. What should I check?

Confirm Node.js is v18 or higher and that the JSON is valid. If you use Node Version Manager, replace `npx` in `command` with its full path, as the documentation advises. Then fully restart the client, since most clients only read the config at launch.

+I get authentication or scope errors from Xero. How do I fix them?

Check that the client ID and secret belong to a Custom Connection and that every scope in the relevant list is added. Use SCOPES_V1 for connections created before Apr 29, 2026 and SCOPES_V2 from that date. If you set `XERO_SCOPES`, make sure it is space-separated and matches the connection's scopes.

+Why is the server ignoring my client ID and using the wrong account?

If `XERO_CLIENT_BEARER_TOKEN` is set, the documentation says it takes precedence over `XERO_CLIENT_ID`. Remove the bearer token variable if you want Custom Connection credentials. Also check that Payroll tools are only used with a Demo Company or organisation in the NZ or UK region.

Written Oct 13, 2026 from the vendor documentation. Exact menus, addresses and commands change; the official documentation is the source of truth.