Xero MCP Server: Complete Guide

Modern accounting platforms expose thousands of API endpoints, but large language models cannot safely use those APIs on their own.

They need a standardized interface that allows them to discover available capabilities, execute operations, and authenticate securely.

That's exactly what the official Xero MCP Server provides.

The Xero MCP Server is an official implementation of the Model Context Protocol (MCP) that acts as a bridge between AI assistants and the Xero Accounting API. Instead of building custom integrations for every AI framework, developers can expose standardized MCP Tools that allow compatible AI clients to interact with Xero accounting data through a consistent protocol. Xero includes the MCP Server as part of its official AI Toolkit alongside its Agent SDK, CLI, and prompt resources.

Rather than writing custom API wrappers for Claude, Cursor, OpenAI Agents, or future MCP-compatible clients, developers can implement one MCP interface that works across the ecosystem.

Throughout this guide you'll learn:

• what the official Xero MCP Server is
• how it works internally
• how authentication works
• how to configure and test the server
• which accounting capabilities it exposes
• how to use it with Claude, Cursor, and other MCP clients
• common setup and authentication problems
• security best practices
• how to evaluate production readiness before deployment

Rather than repeating the official documentation, this guide focuses on how experienced developers actually deploy and validate the Xero MCP Server in real-world AI workflows.

What Is the Xero MCP Server?

The Xero MCP Server is the official Model Context Protocol server published by Xero.

Its purpose is to expose Xero Accounting functionality through standardized MCP Tools that AI assistants can discover and execute.

Instead of calling the Xero REST API directly, an MCP client communicates with the MCP Server, which then performs the necessary authentication, authorization, and API requests against Xero.

This provides a consistent interface regardless of which AI assistant or agent framework you're using.

Depending on configuration and permissions, the server can expose capabilities related to:

• Contacts
• Invoices
• Accounts
• Bank transactions
• Reports
• Organizations
• Payments
• Additional Accounting API resources

The exact capabilities depend on the authenticated tenant, OAuth scopes, and the current implementation of the official server.

Why Use the Xero MCP Server Instead of Calling the API Directly?

Many developers ask a reasonable question:

Why introduce another layer instead of calling the Xero API directly?

For traditional applications, direct API access is often the right choice.

For AI assistants, however, the requirements are different.

An AI model needs to:

• discover available capabilities
• understand tool descriptions
• validate parameters
• invoke operations consistently
• receive structured responses

The Model Context Protocol was designed specifically for this interaction pattern.

Instead of creating custom integrations for every AI framework, developers expose MCP Tools once and allow compatible clients to discover them automatically.

This significantly reduces integration complexity while improving interoperability across the growing MCP ecosystem.

How the Xero MCP Server Works

At a high level, the architecture looks like this:

          Claude / Cursor / AI Agent
                    │
                    ▼
             Xero MCP Server
                    │
             OAuth 2 Authentication
                    │
                    ▼
           Xero Accounting API
                    │
                    ▼
     Contacts • Invoices • Reports
     Payments • Accounts • Banking

The AI assistant never communicates with the Xero API directly.

Instead, it sends MCP Tool requests to the Xero MCP Server.

The server:

1. validates the request,
2. authenticates using OAuth,
3. calls the Xero Accounting API,
4. returns structured data back through the MCP protocol.

This architecture separates AI interaction from business logic while allowing Xero's existing security model to remain unchanged.

Key Features

The official Xero MCP Server is designed for accounting workflows rather than general API experimentation.

Typical capabilities include:

• managing contacts
• creating and updating invoices
• retrieving accounting information
• working with the chart of accounts
• accessing reports
• interacting with organizations
• OAuth-based authentication
• standardized MCP Tool discovery

As the project evolves, Xero may introduce additional MCP Tools and accounting capabilities through future releases.

Prerequisites

Before installing the Xero MCP Server, it's worth understanding what is required.

Unlike many local MCP servers, the Xero MCP Server connects to a live accounting platform that protects financial data through OAuth authentication and organization-level permissions.

To get started, you'll need:

• a Xero account
• access to a Xero organization (a Demo Company is recommended for testing)
• a Xero Developer account
• a registered Xero application
• OAuth credentials
• Node.js 18 or newer
• npm or pnpm

If you're experimenting for the first time, Xero recommends using a Demo Company, which includes pre-populated accounting data and can be reset whenever needed. This makes it an ideal environment for learning and testing without affecting real financial records.

Authentication

Authentication is the most important part of the Xero MCP Server.

Unlike public APIs that rely on static API keys, Xero uses OAuth 2.0 to ensure that every request is performed on behalf of an authorized organization and user.

The official Xero MCP Server currently supports two authentication models.

Option 1: Custom Connections

For most developers, Custom Connections are the recommended approach.

This model is particularly useful when:

• developing locally
• testing with Claude Desktop
• experimenting with Cursor
• building internal automations
• working with a single Xero organization

In this mode, you configure your application using:

• Client ID
• Client Secret

The MCP Server performs OAuth authentication and securely exchanges tokens before communicating with the Xero Accounting API.

According to Xero, this is the preferred approach for local development and third-party MCP clients such as Claude Desktop.

Option 2: Bearer Token Authentication

The second authentication model uses a bearer token.

This model is designed for scenarios where the MCP client performs the OAuth flow itself and provides an access token to the server.

This approach is more appropriate for:

• multi-user applications
• enterprise deployments
• hosted MCP services
• dynamic user authentication

Rather than embedding client credentials inside the server configuration, each authenticated user supplies their own access token during execution.

OAuth Scopes

OAuth scopes determine what the MCP Server is allowed to access.

For example, different scopes may grant permission to:

• read invoices
• create invoices
• access contacts
• retrieve accounting reports
• work with accounts
• manage payments

The official implementation automatically attempts to use the recommended scopes and falls back when appropriate, while also allowing developers to override them through environment variables when necessary.

Granting only the scopes required for your workflow follows the principle of least privilege and reduces unnecessary exposure of accounting data.

Installation

Installing the official Xero MCP Server is straightforward.

The project is distributed through npm and can be executed directly without cloning the repository.

A typical configuration uses:

npx -y @xeroapi/xero-mcp-server@latest

The server can then be referenced from any compatible MCP client, including Claude Desktop and other MCP-enabled development tools.

Connecting the Xero MCP Server to Claude Desktop

One of the most common deployment scenarios is Claude Desktop.

The official repository includes an example claude_desktop_config.json configuration demonstrating how to register the server using npx together with the required environment variables.

The overall flow is simple:

Claude Desktop
        │
        ▼
Xero MCP Server
        │
        ▼
OAuth Authentication
        │
        ▼
Xero Accounting API
        │
        ▼
Accounting Data

Once authentication succeeds, Claude can discover the available MCP Tools automatically.

No custom plugin or bespoke integration layer is required because Tool discovery is handled through the Model Context Protocol itself.

Verifying the Installation

After connecting successfully, verify that the server behaves as expected before using it with production accounting data.

A basic validation checklist includes:

• successful OAuth authentication
• organization access confirmed
• Tools discovered correctly
• invoices accessible
• contacts accessible
• expected permissions available
• no authentication errors
• expected Resources available (if supported)

Testing these items early prevents many of the configuration issues developers typically encounter during their first deployment.

Real-World Use Cases

The Xero MCP Server becomes most valuable when it's used to automate accounting workflows that would otherwise require multiple API calls or manual interaction with the Xero interface.

Instead of asking an AI assistant to "figure out" how to call the Xero API, developers expose standardized MCP Tools that the model can discover and execute safely.

Below are several practical examples.

Create Draft Invoices

One of the most common use cases is invoice creation.

Instead of manually entering invoice details, an AI assistant can collect the required information through conversation and create a draft invoice.

Example:

Create a draft invoice for Acme Ltd with three consulting hours at $150 per hour.

The MCP Server handles:

• contact lookup
• invoice creation
• line items
• tax handling
• API communication

while the AI assistant focuses only on understanding the user's request.

This significantly reduces the amount of custom integration logic developers need to build.

Retrieve Customer Information

Instead of navigating through the Xero interface, users can ask questions naturally.

Examples include:

• Find all customers created this month.
• Show overdue customers.
• Display customer balances.
• List inactive contacts.

The MCP Server converts those requests into appropriate Xero API operations while preserving OAuth permissions.

Query Financial Reports

Another common scenario is financial reporting.

Rather than exporting reports manually, developers can expose reporting Tools that allow AI assistants to retrieve information such as:

• Balance Sheet
• Profit and Loss
• Trial Balance
• Accounts
• Journals

This enables conversational reporting while still relying on the official Xero Accounting API.

Manage Contacts

The server also supports contact management.

Typical operations include:

• creating contacts
• updating contacts
• retrieving customer information
• searching suppliers
• viewing organization details

Because these operations are exposed as MCP Tools, AI clients can discover them automatically instead of relying on custom prompts or API wrappers.

Banking Workflows

Organizations can also automate banking-related tasks.

Depending on permissions and available Tools, developers can:

• retrieve bank transactions
• create bank transactions
• update transactions
• reconcile accounting data

This allows AI assistants to participate in bookkeeping workflows while still respecting Xero's OAuth authorization model.

Testing the Xero MCP Server

Before connecting an AI assistant to live accounting data, validate the server independently.

The recommended workflow is:

Install Server
       │
       ▼
Authenticate with OAuth
       │
       ▼
Verify Organization Access
       │
       ▼
Inspect Available Tools
       │
       ▼
Execute Simple Queries
       │
       ▼
Validate Responses
       │
       ▼
Connect Your MCP Client

Following this sequence helps identify configuration problems before they affect production workflows.

Using MCP Inspector

The easiest way to validate the server is with MCP Inspector.

Inspector allows you to:

• verify OAuth authentication
• inspect available Tools
• execute accounting operations
• inspect returned JSON
• validate parameter schemas
• debug protocol communication

Testing with Inspector first removes uncertainty about whether a problem originates from the server or from the AI client.

If you haven't used Inspector before, see our complete guide:

→ MCP Inspector: Complete Guide

Common Setup Problems

Most installation issues are not caused by the MCP Server itself.

Instead, they usually relate to authentication or configuration.

OAuth Authentication Failed

Symptoms:

• login page does not complete
• authentication fails
• access token cannot be obtained

Typical causes:

• incorrect Client ID
• incorrect Client Secret
• invalid Redirect URI
• OAuth application misconfiguration

Verify the application configuration inside the Xero Developer Portal before troubleshooting the MCP client.

Organization Cannot Be Accessed

Authentication succeeds but no accounting data appears.

This usually means:

• the wrong organization was selected
• tenant authorization was not granted
• the account lacks permissions

Testing with a Xero Demo Company is often the easiest way to isolate permission issues.

No Tools Are Available

If the server starts successfully but exposes no Tools, verify:

• OAuth completed successfully
• required scopes were granted
• the server started correctly
• environment variables were loaded

In most cases, Tool discovery problems originate from configuration rather than the MCP implementation itself.

Claude Cannot Execute Accounting Actions

If Claude discovers the server but cannot execute operations:

• verify OAuth scopes
• inspect Tool parameters
• validate organization permissions
• test the same Tool using MCP Inspector

If the Tool works correctly inside Inspector, the issue is likely related to the MCP client configuration rather than the Xero MCP Server itself.

Security Best Practices

The Xero MCP Server provides secure access to accounting data, but secure deployment depends on much more than simply completing the OAuth flow.

Because the server can access financial records, invoices, contacts, and organizational data, it should be treated as a production integration rather than a simple development tool.

Following a few best practices significantly reduces operational and security risks.

Apply the Principle of Least Privilege

OAuth scopes determine what the MCP Server is allowed to do.

Avoid granting permissions that your workflow doesn't actually require.

For example, if your AI assistant only needs to read invoices, it should not also receive permissions to modify contacts or create payments.

Limiting permissions reduces the impact of credential compromise while making audits much easier.

Use a Dedicated Xero Application

Avoid sharing OAuth credentials across multiple projects.

Instead:

• create a dedicated Xero Developer application
• separate development and production environments
• rotate credentials when appropriate
• review application permissions regularly

Keeping environments isolated reduces the likelihood of accidental data exposure.

Test Against a Demo Company First

Before connecting an AI assistant to production accounting data, validate your workflow using Xero's Demo Company.

This allows you to:

• test authentication
• execute accounting operations
• verify Tool behaviour
• inspect responses
• experiment safely

without affecting real financial records. Xero recommends the Demo Company as the preferred environment for development and testing.

Validate Every Tool Before Production

Don't assume that successful authentication means the integration is production-ready.

Validate:

• every exposed Tool
• expected parameters
• returned responses
• error handling
• authorization behaviour

A small configuration mistake is much easier to fix before the server becomes part of an automated workflow.

Protect OAuth Credentials

Client IDs and Client Secrets should never be:

• committed to Git
• hardcoded into the source code
• shared through chat
• stored in public repositories

Use secure environment variables or a dedicated secrets management solution instead.

Review Logging Carefully

Accounting systems often contain sensitive financial information.

Avoid logging:

• OAuth tokens
• customer financial data
• invoice contents
• payment details
• personally identifiable information (PII)

Logs should provide enough information for troubleshooting without exposing confidential business information.

Xero MCP Server vs Direct Xero API

Developers sometimes wonder whether they should use the official MCP Server or integrate directly with the Xero API.

The answer depends on the type of application you're building.

For AI assistants, agent frameworks, and MCP-compatible clients, the official MCP Server provides a much more natural integration model.

For conventional web applications, backend services, and custom software, the REST API remains the better choice.

The two approaches complement rather than replace each other.

Evaluating the Xero MCP Server

Getting an MCP Server running is only the first step.

Before using it in production, it's worth evaluating:

• exposed capabilities
• authentication behaviour
• compatibility
• security posture
• governance features
• overall implementation quality

Our public directory includes an independently generated profile for the official Xero MCP Server.

You can review the available Tools, implementation details, and public metadata here:

→ Xero Accounting MCP Profile

If you're interested in a deeper technical assessment, you can also review the public security report:

→ Xero Accounting MCP Security Report

These reports provide an additional perspective beyond functional testing and can help identify areas worth reviewing before deploying the server in production.

Best Practices

After reviewing the official documentation and testing the server, several recommendations consistently stand out.

Keep Authentication Separate

Avoid mixing authentication logic with business logic.

Keeping OAuth isolated makes troubleshooting much easier and reduces the risk of introducing security issues during future updates.

Test With MCP Inspector First

Before connecting Claude, Cursor, or another AI client, validate the server independently.

Using MCP Inspector allows you to verify:

• OAuth authentication
• Tool discovery
• Tool execution
• returned JSON
• error handling

without introducing client-specific variables.

Verify Before Deployment

Successful Tool execution does not necessarily mean the server is production-ready.

Review:

• permissions
• exposed capabilities
• authentication
• security controls
• operational behaviour

before allowing AI assistants to interact with real accounting data.

Keep the Official Server Updated

Because the Xero MCP Server is actively maintained, update it regularly to benefit from new features, compatibility improvements, and security fixes published by Xero.

Final Thoughts

The official Xero MCP Server makes it significantly easier to connect AI assistants with Xero's accounting platform through the Model Context Protocol.

Rather than building custom integrations for every AI framework, developers can expose standardized MCP Tools that work across compatible clients while continuing to rely on Xero's existing OAuth security model.

Whether you're building an internal finance assistant, automating accounting workflows, or experimenting with agentic AI, the Xero MCP Server provides a solid foundation for secure and standardized integrations.

Start with a Demo Company, validate every Tool using MCP Inspector, and review production readiness before connecting the server to live accounting data.

Combined with thorough testing, careful permission management, and production verification, it enables organizations to adopt AI-powered accounting workflows with greater confidence.

Official References

This guide is based on the official Xero AI documentation, the official Xero MCP Server repository, and Xero's developer resources.

• Xero AI Toolkit
• Official Xero MCP Server GitHub Repository
• Xero Developer Documentation
• Xero OAuth 2.0 Overview
• Xero Agent Toolkit
• Xero Accounting API Overview

Related Resources

• Xero Accounting MCP Profile
• Xero Accounting MCP Security Report
• MCP Inspector: Complete Guide
• OpenAPI to MCP: Complete Guide
• Running MCP in Production
• How to Secure an MCP Server
• MCP Security Best Practices
• Why Security Teams Resist MCP
• Verify Any MCP Server
• Verified MCP Directory

Verify the Xero MCP Server

Installing the Xero MCP Server is only the first step.

Before connecting it to production accounting data or AI-powered workflows, it's worth validating that the server is configured correctly, exposes the expected capabilities, and follows security best practices.

MCPForge helps you evaluate MCP servers by analyzing:

• Compatibility with the Model Context Protocol
• Available Tools, Resources, and Prompts
• Authentication and configuration
• Security posture
• Governance capabilities
• Health and implementation quality

Review the public Xero Accounting MCP profile, explore the security assessment, or verify your own MCP server to identify potential issues before deploying it to production.

→ Verify Your MCP Server