Merge Unified's Xero integration Merge Agent Handler's Xero MCP server

Connect your AI Agents to Xero in minutes

Merge lets you securely connect your agents to Xero and thousands of tools instantly

Start building for free

Read docs

Xero

Learn more about Merge Agent Handler

Available tools

list_accounts

List all chart of accounts. Filter by Type or Class using 'where' parameter. Returns account codes needed for invoices and transactions.

get_account

Get a single account by ID with full details including reporting codes.

create_account

Create a new account in the chart of accounts. Requires Name, Code (unique), and Type. Use list_accounts to check existing codes.

list_bank_transactions

List bank transactions with pagination (100 per page). Filter by type (RECEIVE/SPEND) using 'where' parameter.

get_bank_transaction

Get a single bank transaction by ID with full details including line items.

create_bank_transaction

Create a bank transaction. Requires Type (RECEIVE/SPEND), Contact, BankAccount, and LineItems. Use list_accounts to find bank account IDs.

update_bank_transaction

Update a bank transaction. Only AUTHORISED transactions can be updated. Use getbanktransaction to check status.

list_contacts

List contacts with pagination (100 per page). Supports filtering via 'where' parameter. Use pageinfo.hasnext_page to check for more results.

get_contact

Get a single contact by ID with full details including addresses and phone numbers.

create_contact

Create a new contact. Name is required. Use list_contacts to check for duplicates first.

update_contact

Update an existing contact. Only provided fields are updated. Use get_contact to see current values.

archive_contact

Archive a contact by setting its status to ARCHIVED. Archived contacts can be restored.

list_credit_notes

List credit notes with pagination (100 per page). ACCRECCREDIT=sales credits, ACCPAYCREDIT=purchase credits.

get_credit_note

Get a single credit note by ID with full details including line items and remaining credit.

create_credit_note

Create a credit note. Requires Type (ACCRECCREDIT/ACCPAYCREDIT), Contact, and LineItems. Use list_contacts for ContactIDs.

update_credit_note

Update a credit note. Only DRAFT or SUBMITTED credit notes can be updated. Use getcreditnote to check status.

list_invoices

List invoices with pagination (100 per page). Filter by status or type. ACCREC=sales invoices, ACCPAY=bills.

get_invoice

Get a single invoice by ID with full details including line items, amounts, and payment status.

create_invoice

Create a new invoice. Requires Type (ACCREC/ACCPAY), Contact, and LineItems. Use list_contacts to find ContactIDs.

update_invoice

Update an existing invoice. Only DRAFT or SUBMITTED invoices can be fully updated. Use get_invoice to check status.

void_invoice

Void an invoice. Only AUTHORISED or SUBMITTED invoices can be voided. This cannot be undone.

email_invoice

Email an invoice to the contact. Invoice must be AUTHORISED before it can be emailed.

list_items

List all items (products/services). Returns item codes that can be used on invoices and purchase orders.

get_item

Get a single item by ID with full details including purchase and sales details.

create_item

Create a new item (product/service). Code is required and must be unique. Use list_items to check existing codes.

delete_item

Delete an item. This permanently removes the item. Use list_items to find item IDs.

list_manual_journals

List manual journals with pagination (100 per page). Filter by status using 'where' parameter.

get_manual_journal

Get a single manual journal by ID with full details including journal lines.

create_manual_journal

Create a manual journal. Requires Narration and JournalLines (min 2 lines, debits/credits must balance). Use list_accounts for account codes.

update_manual_journal

Update a manual journal. Only DRAFT journals can be updated. Use getmanualjournal to check status.

get_organisation

Get the current Xero organisation details including name, currency, country, and financial year settings.

list_connections

List all connected Xero organisations (tenants). Use this to discover available tenant IDs.

list_payments

List payments with pagination. Supports filtering via 'where' parameter. Use pageinfo.hasnext_page to check for more results.

get_payment

Get a single payment by ID with full details including related invoice and account info.

create_payment

Create a payment against an invoice or credit note. Requires Account (bank) and Amount. Use listinvoices and listaccounts to find IDs.

list_purchase_orders

List purchase orders with pagination (100 per page). Filter by status using 'where' parameter.

get_purchase_order

Get a single purchase order by ID with full details including line items and delivery info.

create_purchase_order

Create a purchase order. Requires Contact (supplier) and LineItems. Use list_contacts for supplier ContactIDs.

update_purchase_order

Update a purchase order. Only DRAFT or SUBMITTED orders can be updated. Use getpurchaseorder to check status.

list_quotes

List quotes with pagination (100 per page). Filter by status using 'where' parameter.

get_quote

Get a single quote by ID with full details including line items and terms.

create_quote

Create a quote. Requires Contact and LineItems. Use list_contacts to find ContactIDs.

update_quote

Update a quote. Xero requires Contact, Date, and LineItems on every update. Use get_quote to get current values first.

list_tax_rates

List all tax rates configured in the organisation. Returns TaxType codes needed for invoices and transactions.

list_tracking_categories

List all tracking categories and their options. Used for cost center and department tracking on transactions.

list_currencies

List all currencies enabled in the organisation. Returns currency codes for multi-currency invoices.

list_branding_themes

List all branding themes. Returns theme IDs that can be applied to invoices, quotes, and purchase orders.

validate_credential

Validate Xero credentials by listing connected organisations. Returns {success, message}.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Xero MCP server

What is a Xero MCP?

A Xero MCP is an MCP server that gives your agents access to data and functionality inside your Xero organization via tools. Your agents can invoke these tools to create and update invoices, record payments, manage contacts, post journal entries, and more.

Xero offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Xero MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Invoice automation: When a project milestone is marked complete in a project management tool, an agent creates a draft invoice in Xero for the relevant contact and emails it to the client without any manual step in between

Payment reconciliation: An agent monitors incoming bank transactions in Xero, matches them against outstanding invoices by amount and reference, and applies payments automatically to keep the books current

Cross-system expense posting: When expense reports are approved in an expense management tool, an agent creates the corresponding bank transactions and manual journal entries in Xero, eliminating double entry

Accounts receivable reporting: An agent queries Xero for overdue invoices and outstanding balances on a weekly schedule, formats the results, and posts a summary to a Slack channel for the finance team to review

What are popular tools for Xero's MCP server?

Here are some of the most commonly used tools:

create_invoice: creates a new invoice in Xero for a given contact, line items, and due date. Use this when an agent needs to bill a client automatically after a trigger event in another system

list_invoices: retrieves invoices filtered by status, contact, or date range. Helpful when an agent needs to identify outstanding or overdue invoices before taking a collection or reporting action

create_payment: records a payment against an invoice or credit note in Xero. Call this when an agent detects an incoming payment in a bank feed or payment processor and needs to reconcile it automatically

create_contact: adds a new customer or supplier to Xero's contact list. Good for workflows that onboard a new client in a CRM and need to mirror that record in Xero without manual data entry

create_bank_transaction: posts a spend or receive money transaction against a bank account in Xero. Call this when an agent processes an approved expense or reimbursement and needs to record it in the ledger

create_manual_journal: creates a manual journal entry with debit and credit lines. Useful for agents that handle month-end adjustments or intercompany postings triggered by events in another financial system

What makes Merge Agent Handler's Xero MCP server better than alternative Xero MCP servers?

Several factors make Merge Agent Handler's Xero MCP server the stronger choice over building or using an alternative:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Xero, this means you can prevent invoice amounts, bank account details, and contact financial data from being exposed even when the agent has broad read access

Managed authentication and credentials: Merge stores and refreshes Xero credentials on your behalf. You never expose raw OAuth tokens or client secrets to an agent or manage the token rotation cycle manually

Real-time observability and audit trail: Every tool call made against Xero is logged with timestamp, tool name, input parameters, and response metadata. Finance teams can audit exactly what an agent created or modified without instrumenting anything themselves

Tool Packs and controlled access: Tool Packs let you bundle specific Xero tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent built for invoice creation doesn't need access to journal entries or bank transactions

How can I start using Merge Agent Handler's Xero MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).

2. Create a new Tool Pack, then find and enable the Xero connector. Choose which tools to include: enable read tools for reporting and reconciliation use cases, or add write tools if your agent needs to create invoices, record payments, or post journal entries.

3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.

4. From the Registered User detail page, authenticate Xero by completing the OAuth flow. Merge stores and manages the credentials going forward.

5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.

6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Xero tools are now accessible through that endpoint.