Xero MCP Server

chính thức

Tương tác với dữ liệu kế toán trong doanh nghiệp của bạn bằng máy chủ MCP chính thức của chúng tôi

GitHub
313

Tài liệu

Máy chủ Xero MCP

Đây là bản triển khai máy chủ Model Context Protocol (MCP) cho Xero. Nó cung cấp cầu nối giữa giao thức MCP và API của Xero, cho phép truy cập chuẩn hóa vào các tính năng kế toán và kinh doanh của Xero.

Tính năng

  • Xác thực Xero OAuth2 với các kết nối tùy chỉnh
  • Quản lý liên hệ
  • Quản lý Hệ thống tài khoản
  • Tạo và quản lý hóa đơn
  • Tuân thủ giao thức MCP

Điều kiện tiên quyết

  • Node.js (v18 trở lên)
  • npm hoặc pnpm
  • Tài khoản nhà phát triển Xero có thông tin xác thực API

Tài liệu và Liên kết

Thiết lập

Tạo Tài khoản Xero

Nếu bạn chưa có tài khoản và tổ chức Xero, bạn có thể tạo bằng cách đăng ký tại đây bằng bản dùng thử miễn phí.

Chúng tôi khuyên bạn nên bắt đầu với Công ty Demo vì nó có sẵn một số dữ liệu mẫu. Sau khi đăng nhập, hãy chuyển sang công ty đó bằng cách sử dụng menu thả xuống ở góc trên bên trái và chọn "Demo Company". Bạn có thể đặt lại dữ liệu trên Công ty Demo hoặc thay đổi quốc gia bất kỳ lúc nào bằng cách sử dụng menu thả xuống ở góc trên bên trái và điều hướng đến My Xero.

LƯU Ý: Để sử dụng các truy vấn cụ thể về Bảng lương, khu vực phải là NZ hoặc UK.

Xác thực

Có 2 chế độ xác thực được hỗ trợ trong máy chủ Xero MCP:

1. Kết nối Tùy chỉnh

Đây là lựa chọn tốt hơn cho việc kiểm thử và phát triển, cho phép bạn chỉ định id khách hàng và bí mật cho một tổ chức cụ thể. Đây cũng là cách tiếp cận được khuyến nghị nếu bạn đang tích hợp vào các máy khách MCP bên thứ ba như Claude Desktop.

Cấu hình tài khoản Nhà phát triển Xero của bạn

Thiết lập Kết nối Tùy chỉnh theo các hướng dẫn sau: https://developer.xero.com/documentation/guides/oauth2/custom-connections/

Phạm vi Yêu cầu

Các kết nối tùy chỉnh yêu cầu các phạm vi khác nhau tùy thuộc vào thời điểm chúng được tạo. Tất cả các phạm vi trong danh sách liên quan phải được thêm vào kết nối tùy chỉnh của bạn:

Kết nối Tùy chỉnh Được tạoPhạm vi Yêu cầu
Trước ngày 29 tháng 4 năm 2026SCOPES_V1 (quyền đóng gói)
Từ ngày 29 tháng 4 năm 2026SCOPES_V2 (quyền chi tiết)

Lưu ý: Máy chủ MCP tự động thử phạm vi V1 trước và chuyển sang V2 nếu cần.

Bạn có thể ghi đè các phạm vi này bằng cách đặt biến môi trường XERO_SCOPES thành danh sách các phạm vi được phân tách bằng dấu cách.

Tích hợp máy chủ MCP với Claude Desktop

Để thêm máy chủ MCP vào Claude, hãy vào Settings > Developer > Edit config và thêm phần sau vào tệp claude_desktop_config.json của bạn:

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here",
        "XERO_SCOPES": "accounting.invoices accounting.contacts accounting.settings"
      }
    }
  }
}

Biến XERO_SCOPES là tùy chọn. Nếu bỏ qua, các phạm vi mặc định được liệt kê ở trên sẽ được sử dụng.

LƯU Ý: Nếu bạn đang sử dụng Node Version Manager "command": "npx", hãy thay đổi phần đó thành đường dẫn đầy đủ đến tệp thực thi, tức là: your_home_directory/.nvm/versions/node/v22.14.0/bin/npx trên Mac / Linux hoặc "your_home_directory\\.nvm\\versions\\node\\v22.14.0\\bin\\npx" trên Windows

2. Token Mang (Bearer Token)

Đây là lựa chọn tốt hơn nếu bạn cần hỗ trợ nhiều tài khoản Xero trong thời gian chạy và cho phép máy khách MCP thực hiện luồng xác thực (chẳng hạn như PKCE) khi cần. Trong trường hợp này, hãy sử dụng cấu hình sau:

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

LƯU Ý: XERO_CLIENT_BEARER_TOKEN sẽ được ưu tiên hơn XERO_CLIENT_ID nếu được định nghĩa.

Phạm vi Yêu cầu cho Token Mang

Khi lấy token mang, bạn phải yêu cầu các phạm vi phù hợp. Các phạm vi bạn yêu cầu nên là:

Lưu ý: Một số phạm vi đang bị loại bỏ để thay thế bằng các phạm vi chi tiết hơn. Xem tài liệu Phạm vi Xero OAuth 2.0 để biết chi tiết về lịch trình loại bỏ.

accounting.transactions (Deprecated)
accounting.transactions.read (Deprecated)
accounting.invoices
accounting.invoices.read
accounting.payments
accounting.payments.read
accounting.banktransactions
accounting.banktransactions.read
accounting.manualjournals
accounting.manualjournals.read
accounting.reports.read (Deprecated)
accounting.reports.aged.read
accounting.reports.balancesheet.read
accounting.reports.profitandloss.read
accounting.reports.trialbalance.read
accounting.contacts 
accounting.settings 
payroll.settings 
payroll.employees 
payroll.timesheets

Các Lệnh MCP Khả dụng

  • list-accounts: Lấy danh sách tài khoản
  • list-contacts: Lấy danh sách liên hệ từ Xero
  • list-credit-notes: Lấy danh sách ghi chú có
  • list-invoices: Lấy danh sách hóa đơn
  • list-items: Lấy danh sách mặt hàng
  • list-manual-journals: Lấy danh sách nhật ký thủ công
  • list-organisation-details: Lấy thông tin chi tiết về một tổ chức
  • list-profit-and-loss: Lấy báo cáo lãi lỗ
  • list-quotes: Lấy danh sách báo giá
  • list-tax-rates: Lấy danh sách thuế suất
  • list-payments: Lấy danh sách thanh toán
  • list-trial-balance: Lấy báo cáo cân đối thử
  • list-bank-transactions: Lấy danh sách giao dịch tài khoản ngân hàng
  • list-payroll-employees: Lấy danh sách Nhân viên Bảng lương
  • list-report-balance-sheet: Lấy báo cáo bảng cân đối kế toán
  • list-payroll-employee-leave: Lấy hồ sơ nghỉ phép của Nhân viên Bảng lương
  • list-payroll-employee-leave-balances: Lấy số dư nghỉ phép của Nhân viên Bảng lương
  • list-payroll-employee-leave-types: Lấy danh sách loại nghỉ phép Bảng lương
  • list-payroll-leave-periods: Lấy danh sách kỳ nghỉ phép của Nhân viên Bảng lương
  • list-payroll-leave-types: Lấy danh sách tất cả các loại nghỉ phép khả dụng trong Xero Payroll
  • list-timesheets: Lấy danh sách Bảng chấm công Bảng lương
  • list-aged-receivables-by-contact: Lấy khoản phải thu quá hạn cho một liên hệ
  • list-aged-payables-by-contact: Lấy khoản phải trả quá hạn cho một liên hệ
  • list-contact-groups: Lấy danh sách nhóm liên hệ
  • list-tracking-categories: Lấy danh sách danh mục theo dõi
  • create-bank-transaction: Tạo giao dịch ngân hàng mới
  • create-contact: Tạo liên hệ mới
  • create-credit-note: Tạo ghi chú có mới
  • create-invoice: Tạo hóa đơn mới
  • create-item: Tạo mặt hàng mới
  • create-manual-journal: Tạo nhật ký thủ công mới
  • create-payment: Tạo thanh toán mới
  • create-quote: Tạo báo giá mới
  • create-payroll-timesheet: Tạo Bảng chấm công Bảng lương mới
  • create-tracking-category: Tạo danh mục theo dõi mới
  • create-tracking-option: Tạo tùy chọn theo dõi mới
  • update-bank-transaction: Cập nhật giao dịch ngân hàng hiện có
  • update-contact: Cập nhật liên hệ hiện có
  • update-invoice: Cập nhật hóa đơn nháp hiện có
  • update-item: Cập nhật mặt hàng hiện có
  • update-manual-journal: Cập nhật nhật ký thủ công hiện có
  • update-quote: Cập nhật báo giá nháp hiện có
  • update-credit-note: Cập nhật ghi chú có nháp hiện có
  • update-tracking-category: Cập nhật danh mục theo dõi hiện có
  • update-tracking-options: Cập nhật tùy chọn theo dõi
  • update-payroll-timesheet-line: Cập nhật dòng trên Bảng chấm công Bảng lương hiện có
  • approve-payroll-timesheet: Phê duyệt Bảng chấm công Bảng lương
  • revert-payroll-timesheet: Hoàn tác Bảng chấm công Bảng lương đã phê duyệt
  • add-payroll-timesheet-line: Thêm dòng mới trên Bảng chấm công Bảng lương hiện có
  • delete-payroll-timesheet: Xóa Bảng chấm công Bảng lương hiện có
  • get-payroll-timesheet: Lấy Bảng chấm công Bảng lương hiện có

Để biết tài liệu API chi tiết, vui lòng tham khảo Đặc tả Giao thức MCP.

Dành cho Nhà phát triển

Cài đặt

# Using npm
npm install

# Using pnpm
pnpm install

Chạy bản dựng

# Using npm
npm run build

# Using pnpm
pnpm build

Tích hợp với Claude Desktop

Để liên kết máy chủ Xero MCP đang phát triển của bạn với Claude Desktop, hãy vào Settings > Developer > Edit config và thêm phần sau vào tệp claude_desktop_config.json của bạn:

LƯU Ý: Đối với Windows, hãy đảm bảo đường dẫn args thoát \ giữa các thư mục, tức là "C:\\projects\xero-mcp-server\\dist\\index.js"

{
  "mcpServers": {
    "xero": {
      "command": "node",
      "args": ["insert-your-file-path-here/xero-mcp-server/dist/index.js"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Giấy phép

MIT

Bảo mật

Vui lòng không commit tệp .env hoặc bất kỳ thông tin xác thực nhạy cảm nào vào hệ thống kiểm soát phiên bản (nó được bao gồm trong .gitignore như một mặc định an toàn.)