Xero

Xero MCP 服务

适用于 Xero Accounting API 的 Model Context Protocol（MCP）服务。支持 Claude 和其他兼容 MCP 的客户端管理 Xero 联系人、发票、付款、账户和报告。

功能

• 通过 stdio、HTTP 或 Cloudflare Workers 传输方式管理联系人、发票、付款、科目表和财务报告
• 交互式发票卡片（MCP Apps，SEP-1865）：在 MCP Apps 宿主中，xero_invoices_get 会呈现为内容丰富的只读卡片——默认采用中性样式，可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量进行品牌化
• 网关模式支持按请求提供多租户凭据

一键部署

关于注册表身份验证的说明： 此服务仅依赖公开的 npm 软件包，因此 Cloudflare 和 DigitalOcean 云构建器会匿名安装其依赖项——一键部署无需令牌。（如果未来版本添加了私有 @wyre-ai/* 依赖项，则需要提供具有 read:packages 权限的 GitHub PAT 作为构建变量——Cloudflare Workers 使用 NODE_AUTH_TOKEN，DigitalOcean 使用构建时的 GITHUB_TOKEN 密钥。）

安装已发布的软件包： 发布的软件包位于 GitHub Packages npm 注册表中，每次安装都需要身份验证（即使是公开软件包也一样）。要安装该软件包，请使用具有 read:packages 权限的 GitHub PAT，让 npm 向 npm.pkg.github.com 进行身份验证：

export NODE_AUTH_TOKEN=$(gh auth token)
npm install @wyre-ai/xero-mcp

快速开始

前提条件

• Node.js >= 20
• Xero OAuth2 应用凭据（需要拥有 Xero 开发者账户）

安装和构建

npm install
npm run build

运行（stdio 模式）

XERO_ACCESS_TOKEN=your-access-token XERO_TENANT_ID=your-tenant-id npm start

运行（HTTP 模式）

必须设置 CONDUIT_S2S_SECRET。如果该值为空或为已知占位符，进程会记录错误并以非零状态码退出。它绝不会输出该密钥。

MCP_TRANSPORT=http \
  CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  XERO_ACCESS_TOKEN=your-access-token \
  XERO_TENANT_ID=your-tenant-id \
  npm start

设置密钥且未设置 MCP_HTTP_HOST 时，服务会监听 http://0.0.0.0:8080/mcp。

不设置密钥的本地 HTTP 仅用于开发。服务会记录警告、不检查 X-Gateway-S2S，并且只绑定到 127.0.0.1（忽略非环回地址的 MCP_HTTP_HOST）：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Docker

容器内的镜像会监听 0.0.0.0。请将端口发布到环回地址并传入 S2S 密钥。网关模式不会从环境变量读取 Xero 凭据：

docker build -t xero-mcp .
docker run \
  -e CONDUIT_S2S_SECRET=your-s2s-secret \
  -e AUTH_MODE=gateway \
  -p 127.0.0.1:8080:8080 \
  xero-mcp

单租户 HTTP（AUTH_MODE=env）仍要求提供 S2S 密钥，然后使用 XERO_ACCESS_TOKEN 和 XERO_TENANT_ID：

docker run \
  -e CONDUIT_S2S_SECRET=your-s2s-secret \
  -e AUTH_MODE=env \
  -e XERO_ACCESS_TOKEN=your-access-token \
  -e XERO_TENANT_ID=your-tenant-id \
  -p 127.0.0.1:8080:8080 \
  xero-mcp

Docker Compose

仓库中提供的 Compose 服务采用网关模式。它不会设置 XERO_ACCESS_TOKEN 或 XERO_TENANT_ID，也不会使用 env_file，因此项目的 .env 文件无法将静态供应商凭据注入容器。若未设置 CONDUIT_S2S_SECRET 或其值为空，Compose 将拒绝启动；端口会发布到 127.0.0.1:8080:8080。

CONDUIT_S2S_SECRET=your-s2s-secret docker compose up

环境变量

复制 .env.example。将该文件中的 CONDUIT_S2S_SECRET 留空。

变量	必需	默认值	描述
XERO_ACCESS_TOKEN	用于 stdio 和 AUTH_MODE=env	—	Xero OAuth2 访问令牌。网关 Compose 服务未设置此项。
XERO_TENANT_ID	用于 stdio 和 AUTH_MODE=env	—	Xero 租户 ID（组织）。网关 Compose 服务未设置此项。
MCP_TRANSPORT	否	stdio	传输类型：stdio 或 http
MCP_HTTP_PORT	否	8080	HTTP 服务端口
MCP_HTTP_HOST	否	设置 CONDUIT_S2S_SECRET 时为 0.0.0.0	绑定地址。设置了密钥时会遵循此值。未设置密钥时，MCP_ALLOW_INSECURE_DEV=1 会强制绑定到 127.0.0.1。容器镜像设置为 0.0.0.0。
AUTH_MODE	否	env	env 或 gateway。Compose 设置为 gateway。
CONDUIT_S2S_SECRET	HTTP 必需	—	服务间 HMAC 密钥。若此项为空或为已知占位值，HTTP 启动时会以非零状态退出。切勿提交真实值。此值不会被记录到日志中。
MCP_ALLOW_INSECURE_DEV	否	未设置	在未设置 CONDUIT_S2S_SECRET 时，精确设为 1 以在本地使用 HTTP。此设置会记录警告、跳过 X-Gateway-S2S，且仅绑定到 127.0.0.1。不接受占位密钥。

/health 无需身份验证，也不会读取凭据。stdio 传输不会使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

当设置了 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。该检查由 src/s2s-verify.ts 中的 verifyS2sHeader 执行。

标头值格式为 t=<unix seconds>,v1=<hex>：

• <unix seconds> 是当前 UTC 时间。
• <hex> 是以 CONDUIT_S2S_SECRET 为密钥，对字面字符串 t=<unix seconds>（相同的 t= 前缀和数字）计算得到的 HMAC-SHA256，并编码为 64 个小写十六进制字符。
• 时间戳与服务端时钟的差值必须在 300 秒以内。

若标头缺失或无效，将返回 HTTP 401，且不会读取供应商凭据。密钥不会被记录到日志中。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-Xero-Access-Token: $XERO_ACCESS_TOKEN" \
  -H "X-Xero-Tenant-Id: $XERO_TENANT_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

启动时会拒绝已知占位值（replace-with-a-real-secret、your-s2s-secret、your-secret、changeme、change-me、placeholder、secret、example、replace-me、s2s-secret；忽略大小写和首尾空白），以防止复制的示例用于伪造该标头。使用 openssl rand -hex 32 生成密钥。

网关模式

当 AUTH_MODE=gateway 时，凭据通过 HTTP 标头按请求传递，而非通过环境变量传递：

• X-Xero-Access-Token — OAuth2 访问令牌
• X-Xero-Tenant-Id — Xero 租户 ID

若请求缺少任一标头，将返回 HTTP 401，且不会回退到 XERO_ACCESS_TOKEN 或 XERO_TENANT_ID。设置了 CONDUIT_S2S_SECRET 时，请求还必须包含有效的 X-Gateway-S2S 标头。这样，网关/代理就可以管理多租户凭据。

交互式发票卡片（MCP Apps）

在 MCP Apps 宿主（Claude Desktop/web）中，xero_invoices_get 会渲染为交互式卡片，显示状态、联系人、日期、金额和明细项；在其他宿主中，纯 JSON 行为保持不变。该卡片为只读卡片——发票属于财务记录，因此不会提供写入操作。默认采用中性样式，可通过注入 window.__BRAND__ 或使用 MCP_BRAND_* 环境变量（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）进行品牌定制——无需重新构建。

可用工具

工具按领域组织。使用 xero_navigate 选择领域，然后使用相应领域的工具。

导航

• xero_navigate — 选择领域（contacts、invoices、payments、accounts、reports）
• xero_back — 返回领域选择

联系人

• xero_contacts_list — 分页列出联系人，并支持可选筛选
• xero_contacts_get — 根据 ID 获取联系人详细信息
• xero_contacts_create — 创建新联系人（客户或供应商）
• xero_contacts_search — 按名称搜索联系人

发票

• xero_invoices_list — 列出发票，并支持可选的状态和类型筛选
• xero_invoices_get — 根据 ID 获取发票详细信息
• xero_invoices_create — 创建新发票（销售发票或账单）
• xero_invoices_update_status — 更新发票状态（提交、批准、作废）

付款

• xero_payments_list — 列出付款，并支持可选的状态筛选
• xero_payments_get — 根据 ID 获取付款详细信息
• xero_payments_create — 记录针对发票的付款

账户

• xero_accounts_list — 列出会计科目表，并支持可选的类型/类别筛选
• xero_accounts_get — 根据 ID 获取账户详细信息

报告

• xero_reports_profit_and_loss — 指定日期范围的损益表（利润表）
• xero_reports_balance_sheet — 截至指定日期的资产负债表
• xero_reports_aged_receivables — 按联系人列示的应收账款账龄
• xero_reports_aged_payables — 按联系人列示的应付账款账龄

许可证

Apache-2.0