Xero MCP Server

A production-ready Model Context Protocol server for the Xero Accounting API.

This template lets Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients read and write accounting data through controlled Xero tools.

Built as a starter template for teams that want a secure baseline before adding company-specific accounting workflows.

Who this is for

This repository is useful for:

• developers building AI accounting assistants,

• finance teams experimenting with MCP workflows,

• SaaS teams connecting Xero to internal AI agents,

• platform engineers who need a clean TypeScript MCP server example,

• agencies building custom Xero automations for clients.

Related MCP server: Xero MCP Server

Features

• TypeScript + Express MCP server

• Xero OAuth 2.0 authorization flow

• Refresh-token support

• API key protection for /mcp

• Rate limiting for MCP requests

• Health endpoint at /health

• Structured Pino logging

• Zod-based environment validation

• MCP tools for invoices, contacts, accounts, and payments

• Jest test setup with Supertest

• GitHub Actions CI workflow

Architecture

flowchart LR
  A[Claude / Cursor / MCP Client] -->|POST /mcp| B[Express MCP Server]
  B --> C[API Key Guard]
  C --> D[Rate Limit Middleware]
  D --> E[MCP Tools]
  E --> F[Xero Client]
  F -->|OAuth Bearer Token| G[Xero Accounting API]
  H[Browser] -->|GET /auth/xero| I[Xero OAuth]
  I --> J[Token Store]
  J --> F
  K[MCPForge Verify] --> B

See the larger diagram in docs/architecture.md.

Available MCP tools

Quick start

1. Install dependencies

npm ci

2. Configure environment

cp .env.example .env

Edit .env:

PORT=3000
NODE_ENV=development
LOG_LEVEL=info
SERVER_BASE_URL=http://localhost:3000

MCP_API_KEY=replace-with-a-long-random-secret

XERO_CLIENT_ID=your-xero-client-id
XERO_CLIENT_SECRET=your-xero-client-secret
XERO_REDIRECT_URI=http://localhost:3000/auth/xero/callback
XERO_SCOPES="openid profile email accounting.transactions accounting.contacts accounting.settings offline_access"

RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

3. Run locally

npm run dev

4. Authorize Xero

Open this URL in your browser:

http://localhost:3000/auth/xero

After successful authorization, check status:

curl http://localhost:3000/auth/status

5. Check health

curl http://localhost:3000/health

Xero OAuth setup

In the Xero Developer Portal:

1. Create a new app.

2. Add this redirect URI:

http://localhost:3000/auth/xero/callback

3. Copy the client ID and client secret into .env.

4. Make sure your app has access to the scopes used by this server:

openid profile email accounting.transactions accounting.contacts accounting.settings offline_access

For production, set XERO_REDIRECT_URI to your deployed callback URL, for example:

https://your-domain.com/auth/xero/callback

Connect to Claude Desktop

Build the server first:

npm run build

Then add an MCP server entry in your Claude Desktop configuration.

Example for a local HTTP MCP endpoint:

{
  "mcpServers": {
    "xero": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-API-Key": "replace-with-your-mcp-api-key"
      }
    }
  }
}

Restart Claude Desktop after editing the configuration.

Connect to Cursor

In Cursor, add a new MCP server using the HTTP endpoint:

{
  "name": "xero",
  "url": "http://localhost:3000/mcp",
  "headers": {
    "X-API-Key": "replace-with-your-mcp-api-key"
  }
}

Then restart Cursor or reload the MCP server list.

Security notes

This template is intentionally safer than a minimal demo, but you should still harden it before production use.

Recommended production changes:

• Replace the in-memory token store in src/auth.ts with Redis, Postgres, or another encrypted durable store.

• Store secrets in a managed secret manager, not in plain .env files.

• Rotate MCP_API_KEY regularly.

• Add per-user or per-tenant authorization if multiple users will access the server.

• Restrict write tools such as xero_create_invoice and xero_create_payment behind approvals.

• Add audit logs for every tool call.

• Use HTTPS in production.

• Review scopes and remove anything your use case does not need.

Security Review

You can verify this MCP server with MCPForge:

https://www.mcpforge.tech/verify

MCPForge can help review:

• exposed tools,

• authentication behavior,

• health checks,

• compatibility with MCP clients,

• risk level of write operations,

• security posture before publishing or deployment.

After verification, you can link your public report from this README:

[![Verified by MCPForge](https://www.mcpforge.tech/api/badge/verified/xero-mcp-server)](https://www.mcpforge.tech/verified/xero-mcp-server)

Full MCPForge guide:

https://www.mcpforge.tech/blog/xero-mcp-server

Deployment

A common production setup:

1. Deploy this service to Railway, Render, Fly.io, AWS, GCP, Azure, or a private Kubernetes cluster.

2. Configure environment variables in the hosting provider.

3. Set SERVER_BASE_URL to your public HTTPS URL.

4. Set XERO_REDIRECT_URI to https://your-domain.com/auth/xero/callback.

5. Add the same callback URL in the Xero Developer Portal.

6. Run the OAuth flow once to connect the Xero tenant.

7. Verify /health and /mcp before connecting production AI clients.

8. Run a public or private verification with MCPForge.

Local development commands

npm run lint
npm run typecheck
npm test
npm run build

API endpoints

Repository checklist

Before publishing your fork:

• Replace your-org in the CI badge URL.

• Replace the MCPForge badge slug if your public slug is not xero-mcp-server.

• Replace the blog link with your final MCPForge article URL.

• Add screenshots or a real verification report once available.

• Configure production token storage.

• Review Xero scopes.

License

MIT — see LICENSE.