Xero MCP Server for Accounting and Invoicing

Overview

The Xero MCP Server for Accounting and Invoicing is a lightweight server implementation that exposes a Model Context Protocol (MCP) interface to interact with Xero’s accounting APIs. It translates intent-driven tool calls (for example from an LLM agent) into authenticated Xero API requests, enabling programmatic creation of invoices, retrieval of contacts, account lookups, and other bookkeeping workflows without requiring direct API familiarity.

Designed for developers who want to integrate conversational or agent-driven workflows with Xero, the server centralizes authentication, token management, and request shaping. This simplifies building automation such as automated invoicing, invoice draft generation from chat prompts, and reconciliations driven by business logic models.

Features

• MCP-compatible endpoints to expose Xero actions as callable tools for agents and applications
• OAuth2 token management and Xero tenant handling
• CRUD operations for invoices, contacts, accounts, and payments
• Predefined tool manifests and JSON schemas for safe agent invocation
• Simple Express-based server with extensible routing for adding custom tools
• Built-in logging and basic error handling for development workflows

Installation / Configuration

Requirements:

• Node.js (16+)
• A Xero developer application (client ID and client secret)
• A registered redirect URI for OAuth2 flows

1. Clone and install dependencies

git clone https://github.com/john-zhang-dev/xero-mcp.git
cd xero-mcp
npm install

2. Configure environment variables

Create a .env file in the project root and provide your Xero credentials and server config:

# .env
PORT=3000
XERO_CLIENT_ID=your_xero_client_id
XERO_CLIENT_SECRET=your_xero_client_secret
XERO_REDIRECT_URI=https://your-server.com/oauth/callback
SESSION_SECRET=random-session-secret
NODE_ENV=development

If you are using a reverse proxy / tunnel during development, ensure REDIRECT_URI matches what you registered in the Xero Developer app settings.

3. Run the server

# Development
npm run dev

# Production
npm start

4. Complete OAuth2 authorization

Open the server’s authorization URI (usually served at /auth or available in logs), follow the Xero consent flow, and the server will persist access/refresh tokens and tenant information required for API calls.

Available Resources

The server exposes a set of MCP-style tools and HTTP endpoints. Below is a sample mapping; your deployment may include additional or customized tool handlers.

Example: fetching the tools manifest

curl http://localhost:3000/mcp/tools

Example: invoking the createInvoice tool (JSON body depends on manifest schema)

curl -X POST http://localhost:3000/mcp/invoke/createInvoice \
  -H "Content-Type: application/json" \
  -d '{"contact": {"name":"Acme Corp"}, "lineItems":[{"description":"Service","quantity":1,"unitAmount":100}],"status":"DRAFT"}'

Tool manifest example (JSON snippet suitable for LLM tool registration):

{
  "name": "createInvoice",
  "description": "Create an invoice in Xero (DRAFT or AUTHORIZED)",
  "inputs": {
    "type": "object",
    "properties": {
      "contact": {"type": "object"},
      "lineItems": {"type": "array"},
      "status": {"type": "string", "enum": ["DRAFT","AUTHORISED"]}
    },
    "required": ["contact","lineItems"]
  },
  "invokeUrl": "https://your-server.com/mcp/invoke/createInvoice"
}

Use Cases

• Automated invoicing from chat:

  • A sales assistant LLM collects order details via conversation, then calls the createInvoice tool to generate a draft invoice in Xero. Staff review and finalize the invoice in Xero.

• Billing reconciliation:

  • Periodic agent-driven processes list bank transactions and match them to invoices or create payments by invoking getAccounts, getInvoices, and recordPayment tools.

• Onboarding new customers:

  • When a new customer is added via a CRM chat flow, the system invokes createContact and creates initial invoices or payment reminders automatically.

• Financial reporting via conversational queries:

  • An internal finance bot answers queries like “show outstanding invoices over 30 days” by invoking getInvoices with filters and summarizing results in natural language.

Security & Operational Notes

• Protect client secrets and session tokens. Use secure storage (secrets manager) for production deployments.
• Refresh tokens must be rotated per Xero’s OAuth2 lifecycle; the server includes refresh logic but monitor expiry and handle re-consent when necessary.
• Limit the scope of tools and validate inputs. When exposing tools to LLMs, use strict JSON schemas and input sanitization to prevent malformed requests from reaching Xero.

Troubleshooting

• 401 Unauthorized: Verify client ID/secret, ensure redirect URI matches the Xero app, and confirm tenant authorization.
• Token refresh failures: Check network connectivity and Xero status; re-initiate OAuth flow if refresh token is invalidated.
• Missing tenant-id: After authorization, the server must persist tenant IDs returned by Xero; re-authorize if not present.

For more details and code examples, refer to the repository on GitHub: https://github.com/john-zhang-dev/xero-mcp.