Xero MCP Server

Xero MCP 服务

这是一个适用于 Xero 的模型上下文协议（MCP）服务实现。它在 MCP 协议与 Xero API 之间搭建桥梁，从而以标准化方式访问 Xero 的会计和业务功能。

功能

• 使用自定义连接进行 Xero OAuth2 身份验证
• 联系人管理
• 科目表管理
• 发票创建与管理
• 符合 MCP 协议规范

前提条件

• Node.js（v18 或更高版本）
• npm 或 pnpm
• 拥有 API 凭据的 Xero 开发者账户

文档和链接

• Xero 公共 API 文档
• Xero API 浏览器
• Xero OpenAPI 规范
• Xero-Node 公共 API SDK 文档
• 开发者文档

设置

创建 Xero 账户

如果你还没有 Xero 账户和组织，可以使用免费试用版在此注册创建。

我们建议先使用演示公司，因为其中预先加载了一些示例数据。登录后，使用左上角的下拉菜单选择“演示公司”即可切换。你可以随时使用左上角的下拉菜单并前往 My Xero，重置演示公司的数据或更改国家/地区。

注意：要使用特定于 Payroll 的查询，地区应为 NZ 或 UK。

身份验证

Xero MCP 服务支持 2 种身份验证模式：

1. 自定义连接

此模式更适合测试和开发，你可以为特定组织指定客户端 ID 和密钥。 如果你要将其集成到 Claude Desktop 等第三方 MCP 客户端中，也推荐使用此模式。

配置你的 Xero 开发者账户

按照以下说明设置自定义连接：https://developer.xero.com/documentation/guides/oauth2/custom-connections/

所需作用域

自定义连接所需的作用域取决于创建时间。必须将相应列表中的所有作用域添加到自定义连接：

自定义连接创建时间	所需作用域
2026 年 4 月 29 日之前	SCOPES_V1（捆绑权限）
自 2026 年 4 月 29 日起	SCOPES_V2（细粒度权限）

**注意：**MCP 服务会自动优先尝试 V1 作用域，必要时回退到 V2。

你可以将 XERO_SCOPES 环境变量设置为空格分隔的作用域列表，以覆盖这些设置。

将 MCP 服务与 Claude Desktop 集成

要将 MCP 服务添加到 Claude，请前往“设置”>“开发者”>“编辑配置”，并将以下内容添加到 claude_desktop_config.json 文件中：

{
  "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"
      }
    }
  }
}

XERO_SCOPES 变量为可选项。如果省略，将使用上文列出的默认作用域。

注意：如果你使用 Node Version Manager，请将 "command": "npx" 部分改为可执行文件的完整路径，例如在 Mac / Linux 上使用 your_home_directory/.nvm/versions/node/v22.14.0/bin/npx，或在 Windows 上使用 "your_home_directory\\.nvm\\versions\\node\\v22.14.0\\bin\\npx"

2. Bearer Token

如果你需要在运行时支持多个 Xero 账户，并允许 MCP 客户端按需执行身份验证流程（例如 PKCE），此模式更合适。 在这种情况下，请使用以下配置：

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

注意：如果已定义 XERO_CLIENT_BEARER_TOKEN，它的优先级高于 XERO_CLIENT_ID。

Bearer Token 所需范围

获取 bearer token 时，必须请求相应的范围。请求的范围应为：

注意： 部分范围正在逐步弃用，改用粒度更细的范围。有关弃用时间表的详情，请参阅 Xero OAuth 2.0 Scopes 文档。

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

可用的 MCP 命令

• list-accounts：获取账户列表
• list-contacts：从 Xero 获取联系人列表
• list-credit-notes：获取贷项通知单列表
• list-invoices：获取发票列表
• list-items：获取商品列表
• list-manual-journals：获取手动日记账列表
• list-organisation-details：获取组织详情
• list-profit-and-loss：获取损益报告
• list-quotes：获取报价单列表
• list-tax-rates：获取税率列表
• list-payments：获取付款列表
• list-trial-balance：获取试算平衡表报告
• list-bank-transactions：获取银行账户交易列表
• list-payroll-employees：获取工资单员工列表
• list-report-balance-sheet：获取资产负债表报告
• list-payroll-employee-leave：获取工资单员工的休假记录
• list-payroll-employee-leave-balances：获取工资单员工的休假余额
• list-payroll-employee-leave-types：获取工资单休假类型列表
• list-payroll-leave-periods：获取工资单员工的休假期间列表
• list-payroll-leave-types：获取 Xero Payroll 中所有可用的休假类型列表
• list-timesheets：获取工资单工时表列表
• list-aged-receivables-by-contact：获取联系人的账龄应收款
• list-aged-payables-by-contact：获取联系人的账龄应付款
• list-contact-groups：获取联系人组列表
• list-tracking-categories：获取跟踪类别列表
• create-bank-transaction：创建新的银行交易
• create-contact：创建新联系人
• create-credit-note：创建新的贷项通知单
• create-invoice：创建新发票
• create-item：创建新商品
• create-manual-journal：创建新的手动日记账
• create-payment：创建新付款
• create-quote：创建新报价单
• create-payroll-timesheet：创建新的工资单工时表
• create-tracking-category：创建新的跟踪类别
• create-tracking-option：创建新的跟踪选项
• update-bank-transaction：更新现有银行交易
• update-contact：更新现有联系人
• update-invoice：更新现有草稿发票
• update-item：更新现有商品
• update-manual-journal：更新现有手动日记账
• update-quote：更新现有草稿报价单
• update-credit-note：更新现有草稿贷项通知单
• update-tracking-category：更新现有跟踪类别
• update-tracking-options：更新跟踪选项
• update-payroll-timesheet-line：更新现有工资单工时表中的一行
• approve-payroll-timesheet：批准工资单工时表
• revert-payroll-timesheet：撤销已批准的工资单工时表
• add-payroll-timesheet-line：向现有工资单工时表添加新行
• delete-payroll-timesheet：删除现有工资单工时表
• get-payroll-timesheet：获取现有工资单工时表

如需详细的 API 文档，请参阅 MCP Protocol Specification。

面向开发者

安装

# Using npm
npm install

# Using pnpm
pnpm install

运行构建

# Using npm
npm run build

# Using pnpm
pnpm build

与 Claude Desktop 集成

要将开发中的 Xero MCP 服务连接到 Claude Desktop，请前往 Settings > Developer > Edit config，并将以下内容添加到 claude_desktop_config.json 文件中：

注意：对于 Windows，请确保 args 路径中的文件夹分隔符 \ 已转义，例如 "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"
      }
    }
  }
}

许可证

MIT

安全

请勿将 .env 文件或任何敏感凭据提交到版本控制系统（默认情况下，.env 已包含在 .gitignore 中）。