MCP Directory

How to add Xero MCP Server to Windsurf

Official Xero MCP server for accounting, invoicing, contacts, and payroll via the Xero API. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 317★ · stdio · oauth

Windsurf config for Xero MCP Server

npx -y @xeroapi/xero-mcp-server@latest
{
  "mcpServers": {
    "xero-mcp-server": {
      "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"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Xero MCP Server config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Xero MCP Server's tools become available to Cascade.

Before you start

  • Node.js (v18 or higher)
  • npm or pnpm
  • A Xero developer account with API credentials
  • A Xero account/organisation (a Demo Company is recommended for getting started)
  • A configured Xero Custom Connection (client ID/secret) or a Bearer token with the appropriate OAuth scopes

What Xero MCP Server can do in Windsurf

list-accounts

Retrieve a list of accounts

list-contacts

Retrieve a list of contacts from Xero

list-credit-notes

Retrieve a list of credit notes

list-invoices

Retrieve a list of invoices

list-items

Retrieve a list of items

list-manual-journals

Retrieve a list of manual journals

list-organisation-details

Retrieve details about an organisation

list-profit-and-loss

Retrieve a profit and loss report

Security

Do not commit your .env file or any sensitive credentials to version control (it is included in .gitignore as a safe default). Authentication requires Xero Custom Connection client ID/secret or a Bearer token; configure the minimum required OAuth scopes for your use case. To use Payroll-specific queries, the organisation region must be NZ or UK.

Xero MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Xero MCP Server config there under the "mcpServers" key and restart the client.

Is Xero MCP Server safe to use with Windsurf?

Do not commit your .env file or any sensitive credentials to version control (it is included in .gitignore as a safe default). Authentication requires Xero Custom Connection client ID/secret or a Bearer token; configure the minimum required OAuth scopes for your use case. To use Payroll-specific queries, the organisation region must be NZ or UK.

What authentication modes are supported?

Two modes: Custom Connections (client ID/secret, recommended for testing/development and 3rd-party MCP clients like Claude Desktop) and Bearer Token (for supporting multiple Xero accounts at runtime, where the MCP client executes an auth flow such as PKCE). The XERO_CLIENT_BEARER_TOKEN takes precedence over XERO_CLIENT_ID if defined.

Do I need to configure OAuth scopes?

Yes. Custom connections require different scopes depending on when they were created (SCOPES_V1 before Apr 29, 2026; SCOPES_V2 from that date). The server tries V1 first and falls back to V2. You can override scopes via the optional XERO_SCOPES environment variable as a space-separated list.

Are there region restrictions for Payroll?

Yes. To use Payroll-specific queries, the organisation region must be either NZ or UK.

View repo Full Xero MCP Server page