xero-mcp 1.1.2 → 1.2.0

package/README.md

@@ -1,89 +1,109 @@
 # Xero MCP Server
 
+![](https://badge.mcpx.dev?type=server "MCP Server")
+[![smithery badge](https://smithery.ai/badge/xero-mcp)](https://smithery.ai/server/@john-zhang-dev/xero-mcp)
+
 This MCP server allows Clients to interact with [Xero Accounting Software](https://www.xero.com).
 
 ## Get Started
 
 1. Make sure [node](https://nodejs.org) and [Claude Desktop](https://claude.ai/download) are installed.
 
-2. Create an OAuth 2.0 app in Xero to get a *CLIENT_ID* and *CLIENT_SECRET*.
+2. Create an OAuth 2.0 app in Xero to get a _CLIENT_ID_ and _CLIENT_SECRET_.
 
-    * Create a free Xero user account (if you don't have one) 
-    * Login to Xero Developer center https://developer.xero.com/app/manage/
-    * Click New app
-    * Enter a name for your app
-    * Select Web app
-    * Provide a valid URL (can be anything valid eg. https://www.myapp.com)
-    * Enter redirect URI: `http://localhost:5000/callback`
-    * Tick to Accept the Terms & Conditions and click Create app
-    * On the left-hand side of the screen select Configuration
-    * Click Generate a secret
+   - Create a free Xero user account (if you don't have one)
+   - Login to Xero Developer center https://developer.xero.com/app/manage/
+   - Click New app
+   - Enter a name for your app
+   - Select Web app
+   - Provide a valid URL (can be anything valid eg. https://www.myapp.com)
+   - Enter redirect URI: `http://localhost:5000/callback`
+   - Tick to Accept the Terms & Conditions and click Create app
+   - On the left-hand side of the screen select Configuration
+   - Click Generate a secret
 
 3. Modify `claude_desktop_config.json` file
 
-    ```json
-    {
-        "mcpServers": {
-            "xero-mcp": {
-                "command": "npx",
-                "args": ["-y", "xero-mcp"],
-                "env": {
-                    "XERO_CLIENT_ID": "YOUR_CLIENT_ID",
-                    "XERO_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
-                    "XERO_REDIRECT_URI": "http://localhost:5000/callback"
-                }
-            }
-        }
-    }
-    ```
+   ```json
+   {
+     "mcpServers": {
+       "xero-mcp": {
+         "command": "npx",
+         "args": ["-y", "xero-mcp@latest"],
+         "env": {
+           "XERO_CLIENT_ID": "YOUR_CLIENT_ID",
+           "XERO_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
+           "XERO_REDIRECT_URI": "http://localhost:5000/callback"
+         }
+       }
+     }
+   }
+   ```
 
 4. Restart Claude Desktop
 
+5. When the Client decides to access a Xero tool for the first time, a Xero login page will pop up to ask your consent. Complete the auth flow and manually close the web page (as the Xero page will not auto close in this version)
+
+   **Privacy alert: after completing the Xero OAuth2 flow, your Xero data may go through the LLM that you use. If you are doing testing you should authorize to your [Xero Demo Company](https://central.xero.com/s/article/Use-the-demo-company).**
+
 ## Tools
 
-- authenticate
+- `authenticate`
+
+  Authenticate with Xero using OAuth2
+
+- `get_balance_sheet`
+
+  Retrieves report for balancesheet
+
+- `list_accounts`
+
+  Retrieves the full chart of accounts
+
+- `list_bank_transactions`
+
+  Retrieves any spent or received money transactions
 
-    Authenticate with Xero using OAuth2
+- `list_contacts`
 
-- list_accounts
+  Retrieves all contacts in a Xero organisation
 
-    List all accounts
+- `list_invoices`
 
-- list_bank_transactions
+  Retrieves sales invoices or purchase bills
 
-    List all bank transactions
+- `list_journals`
 
-- list_contacts
+  Retrieves journals
 
-    List all contacts
+- `list_organisations`
 
-- list_invoices
+  Retrieves Xero organisation details
 
-    List all invoices
+- `list_payments`
 
-- list_journals
+  Retrieves payments for invoices and credit notes
 
-    List all journals
+- `list_quotes`
 
-- list_organisations
+  Retrieves sales quotes
 
-    List all organisations
+## Examples
 
-- list_payments
+- "Visualize my financial position over the last month"
 
-    List all payments
+    <img src="https://github.com/john-zhang-dev/assets/blob/main/xero-mcp/demo1.jpg?raw=true" width=50% height=50%>
 
-- list_quotes
+- "Track my spendings over last week"
 
-    List all quotes
+    <img src="https://github.com/john-zhang-dev/assets/blob/main/xero-mcp/demo2.jpg?raw=true" width=50% height=50%>
 
 ## WIP Features
 
 - Tools that allow new transactions to be added to Xero
-- Docker support
 
 If you have additional requirements, please open an issue on this github repository.
 
 ## License
 
-MIT
+MIT

package/build/Tools/{Accounts.js → Accounting/Accounts.js}

@@ -1,9 +1,9 @@
-import { XeroClientSession } from "../XeroApiClient.js";
+import { XeroClientSession } from "../../XeroApiClient.js";
 import { z } from "zod";
 export const ListAccountsTool = {
     requestSchema: {
         name: "list_accounts",
-        description: "List all accounts",
+        description: "Retrieves the full chart of accounts",
         inputSchema: { type: "object", properties: {} },
         output: { content: [{ type: "text", text: z.string() }] },
     },

package/build/Tools/{BankTransactions.js → Accounting/BankTransactions.js}

@@ -1,9 +1,9 @@
 import { z } from "zod";
-import { XeroClientSession } from "../XeroApiClient.js";
+import { XeroClientSession } from "../../XeroApiClient.js";
 export const ListBankTransactionsTool = {
     requestSchema: {
         name: "list_bank_transactions",
-        description: "List all bank transactions",
+        description: "Retrieves any spent or received money transactions",
         inputSchema: { type: "object", properties: {} },
         output: { content: [{ type: "text", text: z.string() }] },
     },

package/build/Tools/{Contacts.js → Accounting/Contacts.js}

@@ -1,9 +1,9 @@
-import { XeroClientSession } from "../XeroApiClient.js";
+import { XeroClientSession } from "../../XeroApiClient.js";
 import { z } from "zod";
 export const ListContactsTool = {
     requestSchema: {
         name: "list_contacts",
-        description: "List all contacts",
+        description: "Retrieves all contacts in a Xero organisation",
         inputSchema: { type: "object", properties: {} },
         output: { content: [{ type: "text", text: z.string() }] },
     },

package/build/Tools/{Invoices.js → Accounting/Invoices.js}

@@ -1,9 +1,9 @@
-import { XeroClientSession } from "../XeroApiClient.js";
+import { XeroClientSession } from "../../XeroApiClient.js";
 import { z } from "zod";
 export const ListInvoicesTool = {
     requestSchema: {
         name: "list_invoices",
-        description: "List all invoices",
+        description: "Retrieves sales invoices or purchase bills",
         inputSchema: { type: "object", properties: {} },
         output: { content: [{ type: "text", text: z.string() }] },
     },

package/build/Tools/{Journals.js → Accounting/Journals.js}

@@ -1,9 +1,9 @@
-import { XeroClientSession } from "../XeroApiClient.js";
+import { XeroClientSession } from "../../XeroApiClient.js";
 import { z } from "zod";
 export const ListJournalsTool = {
     requestSchema: {
         name: "list_journals",
-        description: "List all journals",
+        description: "Retrieves journals",
         inputSchema: { type: "object", properties: {} },
         output: { content: [{ type: "text", text: z.string() }] },
     },

package/build/Tools/{Organisations.js → Accounting/Organisations.js}

@@ -1,9 +1,9 @@
 import { z } from "zod";
-import { XeroClientSession } from "../XeroApiClient.js";
+import { XeroClientSession } from "../../XeroApiClient.js";
 export const ListOrganisationsTool = {
     requestSchema: {
         name: "list_organisations",
-        description: "List all organisations",
+        description: "Retrieves Xero organisation details",
         inputSchema: { type: "object", properties: {} },
         output: { content: [{ type: "text", text: z.string() }] },
     },

package/build/Tools/{Payments.js → Accounting/Payments.js}

@@ -1,9 +1,9 @@
-import { XeroClientSession } from "../XeroApiClient.js";
+import { XeroClientSession } from "../../XeroApiClient.js";
 import { z } from "zod";
 export const ListPaymentsTool = {
     requestSchema: {
         name: "list_payments",
-        description: "List all payments",
+        description: "Retrieves payments for invoices and credit notes",
         inputSchema: { type: "object", properties: {} },
         output: { content: [{ type: "text", text: z.string() }] },
     },

package/build/Tools/{Quotes.js → Accounting/Quotes.js}

@@ -1,9 +1,9 @@
-import { XeroClientSession } from "../XeroApiClient.js";
+import { XeroClientSession } from "../../XeroApiClient.js";
 import { z } from "zod";
 export const ListQuotesTool = {
     requestSchema: {
         name: "list_quotes",
-        description: "List all quotes",
+        description: "Retrieves sales quotes",
         inputSchema: { type: "object", properties: {} },
         output: { content: [{ type: "text", text: z.string() }] },
     },

package/build/Tools/McpToolsFactory.js

@@ -1,15 +1,17 @@
-import { ListAccountsTool } from "./Accounts.js";
+import { ListAccountsTool } from "./Accounting/Accounts.js";
 import { AuthenticateTool } from "./Authenticate.js";
-import { ListBankTransactionsTool } from "./BankTransactions.js";
-import { ListContactsTool } from "./Contacts.js";
-import { ListInvoicesTool } from "./Invoices.js";
-import { ListJournalsTool } from "./Journals.js";
-import { ListOrganisationsTool } from "./Organisations.js";
-import { ListPaymentsTool } from "./Payments.js";
-import { ListQuotesTool } from "./Quotes.js";
+import { ListBankTransactionsTool } from "./Accounting/BankTransactions.js";
+import { ListContactsTool } from "./Accounting/Contacts.js";
+import { ListInvoicesTool } from "./Accounting/Invoices.js";
+import { ListJournalsTool } from "./Accounting/Journals.js";
+import { ListOrganisationsTool } from "./Accounting/Organisations.js";
+import { ListPaymentsTool } from "./Accounting/Payments.js";
+import { ListQuotesTool } from "./Accounting/Quotes.js";
+import { GetBalanceSheetTool } from "./Reports/BalanceSheet.js";
 export const McpToolsFactory = (function () {
     const tools = [
         AuthenticateTool,
+        GetBalanceSheetTool,
         ListAccountsTool,
         ListBankTransactionsTool,
         ListContactsTool,

package/build/Tools/Reports/BalanceSheet.js

@@ -0,0 +1,22 @@
+import { XeroClientSession } from "../../XeroApiClient.js";
+import { z } from "zod";
+export const GetBalanceSheetTool = {
+    requestSchema: {
+        name: "get_balance_sheet",
+        description: "Returns a balance sheet for the end of the month of the specified date. It also returns the value at the end of the same month for the previous year.",
+        inputSchema: { type: "object", properties: {} },
+        output: { content: [{ type: "text", text: z.string() }] },
+    },
+    requestHandler: async () => {
+        const response = await XeroClientSession.xeroClient.accountingApi.getReportBalanceSheet(XeroClientSession.activeTenantId());
+        const reports = response.body.reports || [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(reports),
+                },
+            ],
+        };
+    },
+};

package/build/XeroApiClient.js

@@ -3,7 +3,7 @@ import "dotenv/config";
 const client_id = process.env.XERO_CLIENT_ID;
 const client_secret = process.env.XERO_CLIENT_SECRET;
 const redirectUrl = process.env.XERO_REDIRECT_URI;
-const scopes = "offline_access openid profile accounting.transactions accounting.contacts.read accounting.journals.read";
+const scopes = "offline_access openid profile accounting.transactions.read accounting.contacts.read accounting.journals.read accounting.reports.read";
 if (!client_id || !client_secret || !redirectUrl) {
     throw Error("Environment Variables not all set - please check your .env file in the project root or create one!");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xero-mcp",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "A Model Context Protocol server allows Clients to interact with Xero",
   "author": "Jianyang Zhang",
   "type": "module",