Xero

Xero MCP サーバー

Xero Accounting API 用の Model Context Protocol（MCP）サーバーです。Claude やその他の MCP 対応クライアントから、Xero の連絡先、請求書、支払い、勘定科目、レポートを管理できます。

機能

• stdio、HTTP、Cloudflare Workers トランスポートを通じた、連絡先、請求書、支払い、勘定科目表、財務レポートの操作
• インタラクティブな請求書カード（MCP Apps、SEP-1865）：xero_invoices_get は MCP Apps ホストでリッチな読み取り専用カードとして表示されます。デフォルトはニュートラルで、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 なしでローカル HTTP を使用するには、正確に 1 を設定します。警告がログに記録され、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> は、リテラル文字列 t=<unix seconds>（同じ t= のプレフィックスと数字）を CONDUIT_S2S_SECRET でキー設定して HMAC-SHA256 で計算し、64 文字の小文字の 16 進数としてエンコードした値です。
• タイムスタンプはサーバーの時計との差が 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