用途

xero-mcp-server 是面向 Xero 的 Model Context Protocol（MCP）服务器实现。它在 MCP 协议与 Xero API 之间提供桥梁，使 MCP 客户端能够以标准化方式访问 Xero 的会计与业务功能。该服务器遵循 MCP 协议规范，协议介绍参见 https://modelcontextprotocol.io/introduction。

主要能力

根据资料，该服务器提供以下能力：

Xero OAuth2 认证，支持自定义连接（Custom Connections）
联系人管理
会计科目表（Chart of Accounts）管理
发票创建与管理
MCP 协议合规

环境要求

Node.js（v18 或更高版本）
带 API 凭据的 Xero 开发者账户

准备工作

如果还没有 Xero 账户和组织，可通过注册免费试用创建。建议先使用 Demo Company 开始，因为它带有一些预加载的示例数据。登录后，可使用左上角下拉菜单选择 "Demo Company" 切换。可随时使用左上角下拉菜单进入 My Xero 重置 Demo Company 的数据或更改国家。

注意：若要使用 Payroll 相关的查询，地区应为 NZ 或 UK。

认证方式

Xero MCP 服务器支持 2 种认证模式。

自定义连接（Custom Connections）

这是测试和开发中较好的选择，允许为特定组织指定 client id 和 secret。如果要将其集成到第三方 MCP 客户端（如 Claude Desktop）中，也推荐使用此方式。

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

自定义连接根据创建时间不同需要不同的 scope。相关列表中的所有 scope 都必须添加到自定义连接中：

注意：MCP 服务器会自动先尝试 V1 scope，必要时回退到 V2。

可通过将 XERO_SCOPES 环境变量设置为空格分隔的 scope 列表来覆盖这些默认值。

将 MCP 服务器添加到 Claude：进入 Settings > Developer > Edit config，并将以下内容添加到 claude_desktop_config.json 文件中：

XERO_SCOPES 变量是可选的。如果省略，将使用上面列出的默认 scope。

注意：如果使用 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"。

运行时多账户认证

如果要在运行时支持多个 Xero 账户，并允许 MCP 客户端按需执行认证流程（如 PKCE），这是更好的选择。此时使用以下配置：

注意：如果定义了 XERO_CLIENT_BEARER_TOKEN，它将优先于 XERO_CLIENT_ID。

获取 bearer token 时，必须请求适当的 scope。请求的 scope 应为：

注意：部分 scope 正被弃用，改用更细粒度的 scope。有关弃用时间线的详细信息，请参阅 Xero OAuth 2.0 Scopes 文档。

可用的 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。

与 Claude Desktop 集成

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

注意：Windows 上确保 args 路径中的文件夹之间的 \ 被转义，例如 "C:\projects\xero-mcp-server\dist\index.js"。

安全提示

请勿将 .env 文件或任何敏感凭据提交到版本控制（默认已被包含在 .gitignore 中作为安全默认值）。

xero-mcp-server

工具介绍

用途