xlsx-for-ai について
xlsx-for-aiは、Excelブックの読み取り、編集、検証、比較、分析を行うエージェント向けMCPサーバー兼コマンドラインツールです。構造を保ったまま、ホスト型サービスで数式を再計算します。
主な機能
- 01.xlsxブックの読み書き
- 02数式結果の再計算
- 03ブックの差分比較と検証
- 04書式とブック構造の保持
- 05スプレッドシート内容の分析
- 06対応形式のファイル変換
活用シーン
- 01ブック内の数式結果の確認
- 02参照切れやブック破損の検出
- 03ブックの改訂版同士の比較
- 04スプレッドシートファイルの作成や更新
MCP 対応
stdio経由でMCPクライアントにスプレッドシートツールを提供し、Claude Codeプラグイン向けにはホスト型MCPエンドポイントも用意します。ファイル処理はホスト型サービスで行います。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
78掲載時のツール一覧 · 2 週間前に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| sheet | string | いいえ | シート名またはインデックス（デフォルト：すべてのシート）。 |
| format | enum | いいえ | 出力形式。"md"（Markdown テーブル、デフォルト）、"json"（構造化された行）、または "sql"（CREATE TABLE + INSERTs）を使用します。同義語："markdown"→"md"、"text"→"md"。md | json | sql |
| evaluate | boolean | いいえ | サーバー側で数式を評価します（デフォルト：false）。 |
| file_path | string | はい | .xlsx ファイルの絶対パス。パス文字列はそのまま渡してください。ファイルの読み取り、オープン、base64 エンコードは行わないでください。すべてのファイル I/O はクライアントが処理します。このコネクターの base64 サーフェスは出力専用です（_meta.file_b64）。 |
詳細
xlsx-for-ai
短縮名：xfa — 実際の CLI コマンド（xfa <file>、xfa samples、xfa --version）とプロンプトでの略称（例：「このファイルを読むには xfa を使ってください」）です。xlsx-for-ai と同じエントリーポイントを使用し、内部の xfa_* / XFA_* ブランド表記に合わせています。
検証済みの値、構造を保持、最大 100MB
LLM エージェントによるスプレッドシート作業に欠けていた信頼性レイヤーです。.xlsx ファイルの読み取り、書き込み、差分確認、検証、分析をエンドツーエンドで行い、結合セル、数式、名前付き範囲、条件付き書式、ピボット、グラフを保持します。
xlsx-for-ai により、Claude は実際の Excel ファイルを確実に扱えるようになります。40 種類以上のツールが、pandas 形式のサンドボックスでは失われてしまう構造情報を網羅します。結合セル、名前付き範囲、計算結果付きの数式、条件付き書式、ピボット、スライサー、グラフ、コメント、データの入力規則、ハイパーリンク、シート間の構造、外部リンク、フォームコントロール、VBA マクロ、ドキュメントのプロパティ、保護設定などです。健全性チェック（xlsx_validate）は、ほかのリーダーが気づかないまま見過ごす破損を検出します。ホスト型の再計算エンジンが、提供する値を自社環境内で計算します。提供経路にサードパーティ製の数式エンジンは使用しません。
Claude Code では、コマンド 1 つ：
claude plugin install xlsx-for-ai --marketplace senoff/xlsx-for-ai
続いて /reload-plugins を実行するか、Claude Code を再起動し、/mcp を開いて plugin:xlsx-for-ai:spreadsheets を選択し、一度サインインしてください。Claude Code 2.1.292 以降が必要です（古い場合は claude update を実行してください）。プラグインの詳細は、以下のClaude Code プラグインをご覧ください。
Claude アプリ（claude.ai）では： claude.ai/directory のコネクター一覧から xlsx-for-ai を探し、「接続」をクリックしてください。
npm パッケージ（Claude Code、Cursor、Claude Desktop など）：
npm install -g xlsx-for-ai
グローバルインストールにより、xlsx-for-ai-mcp バイナリが PATH に追加されます。以下の標準設定はこのバイナリを参照します。バージョンを固定したグローバルインストールは高速に起動します（ファイルはホスト型サービスが読み取るため、インターネット接続は引き続き必要です）。新しいバージョンがリリースされたら、npm install -g xlsx-for-ai@latest でアップグレードしてください。
1.5.x からアップグレードする場合： これは機能追加ではなく、アーキテクチャの再設計です。重いローカルエンジンは npm パッケージからなくなりました。すべてのレンダリングはサーバー側で行われます。
cursor-reads-xlsxエイリアスは引き続き機能します。以下の移行をご覧ください。
MCP の設定
エージェントのランタイムに、サーバーを xfa という名前で追加してください（「これを読むには xfa を使って」が解決されます）。初回実行時に、一度だけサインインが必要です。エディターやデスクトップアプリでは、最初のリクエストへの応答として、サインインリンクと短いコードが表示されます。リンクを開いて承認し、もう一度リクエストしてください。または、先にターミナルで xlsx-for-ai login を実行してください（初回サインインをご覧ください）。以前のバージョンで作成したキーは、今のところ引き続き機能します。変更があった場合も、サインインリンクは同じ場所に表示されるため、事前の対応は不要です。
Claude Code
グローバルインストールにより、xfa MCP サーバーが ~/.claude.json に自動登録されます。追加の手順はありません。
npm install -g xlsx-for-ai
インストールスクリプトが実行されない環境（--ignore-scripts、CI、sudo によるインストールなど）では、手動で登録してください。
claude mcp add xfa -- xlsx-for-ai-mcp
確認方法：新しい Claude Code セッションで「どの MCP ツールを使えますか？」と尋ねてください。xlsx_doctor（1 回の呼び出しでヘルスレポートを生成します。不明なブックでは、まずこれを試してください）を含む、52 個の xlsx_* ツールが表示されるはずです。
続いて xfa samples（xlsx-for-ai samples の略称）を実行すると、デモ用ブックが 2 つ作業ディレクトリに作成され、すぐに貼り付けて試せるプロンプトが表示されます。
Claude Desktop
Claude Desktopはファイルを読み取れますが、数式の再計算、大規模なブックの正確な読み取り、実際の.xlsxファイルの返却はできません。xfaサーバーを追加すると、これらが可能になります。インストールによってClaude Desktopの設定は変更されないため、サーバーを自分で追加してください。まずパッケージをインストールし（npm install -g xlsx-for-ai）、次に設定ファイルを開きます。
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - Windows：
%APPDATA%\Claude\claude_desktop_config.json
（Claude Desktopでは、「Settings」→「Developer」→「Edit Config」を選ぶと開きます。）既存のサーバーを残したまま、mcpServersの下にxfaを追加します。
{
"mcpServers": {
"xfa": {
"command": "xlsx-for-ai-mcp"
}
}
}
Claude Desktopを完全に終了してから、再起動します。確認するには、「どのようなMCPツールがありますか？」と尋ね、xfaに52個のxlsx_*ツールが表示されることを確認します。最初のリクエストでは、サインイン用リンクと短いコードが返されます。リンクを開いて承認し、もう一度尋ねてください。
Cursor
設定ファイル：~/.cursor/mcp.json
{
"mcpServers": {
"xfa": {
"command": "xlsx-for-ai-mcp"
}
}
}
確認するには、Cursorの設定 → MCPを開き、xfaに52個のxlsx_*ツールが表示されることを確認します。
Continue
設定ファイル：~/.continue/config.json
{
"mcpServers": [
{
"name": "xfa",
"command": "xlsx-for-ai-mcp"
}
]
}
確認するには、VS Codeを再起動してContinueパネルを開き、MCPサーバーの一覧を確認します。
Codex CLI
コマンドラインで--mcp-serverを渡すか、Codexの設定に追加します。
{
"mcpServers": {
"xfa": {
"command": "xlsx-for-ai-mcp"
}
}
}
確認するには、codex --list-toolsを実行し、52個のxlsx_*ツールが一覧に表示されることを確認します。
Zed
設定ファイル：~/.config/zed/settings.json
{
"context_servers": {
"xfa": {
"command": {
"path": "xlsx-for-ai-mcp"
}
}
}
}
確認するには、Zedのアシスタントパネルを開きます。ツールピッカーにxlsxツールが表示されます。
Windsurf
設定ファイル：~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"xfa": {
"command": "xlsx-for-ai-mcp"
}
}
}
確認するには、Windsurf → Cascade → 設定を開き、xfaが有効なMCPサーバーとして一覧に表示されることを確認します。
カスタムエージェント／API
カスタムMCPクライアントでは、バイナリはxlsx-for-ai-mcp（stdioトランスポート）です。ローカル開発でhttp://localhost:3000に接続するには、XLSX_FOR_AI_API環境変数でAPIのベースURLを上書きします。
生の HTTP API を使用する
MCP クライアントを使うのが簡単ですが、すべてのツールは通常の HTTP エンドポイントでもあるため、SDK がなくても任意の言語から呼び出せます。https://api.xlsx-for-ai.dev/oauth（/oauth/reg、/oauth/device/auth、/oauth/token。resource=https://api.xlsx-for-ai.dev/mcp を指定）で OAuth デバイスフロー（RFC 8628）を使ってサインインし、続いて Authorization: Bearer <access token> を指定して POST https://api.xlsx-for-ai.dev/api/v1/clients を呼び出すと、{ client_id, api_key } が返されます。Authorization: Bearer <api_key> を指定して、任意のツールを呼び出せます。移行期間中は、以前のバージョンで発行された匿名キーも引き続き使用できます。上限については、料金についてをご覧ください。
# Legacy keyless registration (still accepted during the transition; new integrations
# should use the device-flow sign-in above), then convert report.xlsx to Markdown.
# Needs jq, and bash or zsh. The base64 body is passed to curl through a
# process-substitution fd and the token through a --config heredoc on stdin, which
# keeps both out of the argument list. -fsS --max-time makes curl fail loudly on an
# HTTP error or a hang; the guard line stops on a failed key issuance.
KEY=$(curl -fsS --max-time 30 -XPOST https://api.xlsx-for-ai.dev/api/v1/clients \
-H 'Content-Type: application/json' \
-d '{"client_version":"2.0.0","platform":"cli"}' | jq -r .api_key)
[ -n "$KEY" ] && [ "$KEY" != null ] || { echo "key issuance failed"; exit 1; }
curl -fsS --max-time 120 -XPOST https://api.xlsx-for-ai.dev/api/v1/tools/xlsx_convert \
--data-binary @<(base64 < report.xlsx | tr -d '\n' | jq -Rs '{file_b64: ., to: "md"}') \
-H 'Content-Type: application/json' \
--config - <<CFG
header = "Authorization: Bearer $KEY"
CFG
大きすぎるファイルや、利用上限を超えるリクエストには、プランの変更が役立つ場合に upgrade フィールドを含む、型付き JSON エラーが返されます（下記参照）。
レート制限、利用上限超過、サイズ超過のリクエストには、選択肢を示す upgrade フィールドを含む型付き JSON エラー（{ "error": { "code", "message" } }）が返されます。契約の詳細については、GET /api/v1/reference をご覧ください。
すべてのエラーボディは、この形式に厳密に従います。error.code は分岐処理に使う、安定した機械可読キーです。error.message は、何が問題で、何を変更すればよいかを示す、自己修正のための詳細情報です。一部のコードでは、ドキュメントに記載された追加フィールドが返されます（たとえば、シートが見つからない場合の拒否では available_sheets、有料プランが必要な場合の拒否では upgrade）。ただし、ワイヤ上にそれ以上細分化されたエラーサブタイプのフィールドはありません。サーバーは監査用にのみ、より詳細な分類を保持します。
Convert は型付き 501 で拒否する場合があります。 xlsx_convert は、サーバー独自のエンジンのみを使って xlsx、xls、csv、json の入力を変換します。そのエンジンがこれらの入力の変換を拒否した場合（たとえば、表示形式を使うセルや、エンジンでは正確に再現できないキャッシュされていない数式を含む .xlsx を、一部の to=csv 変換で処理する場合。同じファイルでも、通常は to=xlsx または to=json なら変換できます）、API は HTTP 501 とともに、error.code が capability_gap のエラーを返します。メッセージは「xlsx_convert isn't yet supported by our own engine for .xlsx files, and we don't fall back to a full-workbook recompute on this file type ...」という形式です。互換性ライブラリに暗黙的にフォールバックすることはありません。これはクライアントエラーでも一時的なエラーでもないため、同じファイルを再試行しても解決しません。ホスト型 MCP コネクター経由では、同じ拒否がそのメッセージを含む isError: true のツール結果として返されます。特殊な形式（ods、xlsb、fods、および書き込み先の xls／BIFF8）は引き続き従来の経路で処理されるため、影響を受けません。
同じ管理された契約は、2 つのルートから読み取り専用で提供されます。キーなしで API 全体を確認できます。
GET /api/v1/reference— 上記の利用開始手順を含む、安定版として公開されている全 52 ツールをまとめた、人間向けの HTML リファレンスです。GET /api/v1/openapi.json— バージョン管理された OpenAPI 3.1 契約を、そのまま提供します。コード生成ツール、Postman、または Scalar／Redoc から指定してください。
Claude Code プラグイン
Claude Code プラグインを使うと、エージェントをホスト型の xlsx-for-ai ツールに接続できます。スプレッドシートファイルやリンク（.xlsx、.xlsm、.xls、.csv、.tsv、Google スプレッドシート）に対応しており、計算結果に答えが左右される場合、保存済みの値が最新かどうかを確認する場合、または編集可能なスプレッドシートファイルを返す場合に、ツールが役立つことをエージェントに伝えます。
claude plugin install xlsx-for-ai --marketplace senoff/xlsx-for-ai
このコマンドを実行すると、マーケットプレイスが追加され、プラグインがインストールされます。Claude Code 2.1.292 以降が必要です。それより古い場合は、先に claude update を実行してください。
その後、最初に一度だけ /reload-plugins を実行する（または Claude Code を起動する）必要があります。続けて /mcp を実行し、plugin:xlsx-for-ai:spreadsheets サーバーを選択して、ブラウザーでサインインしてください。プラグインはホスト型エンドポイント https://api.xlsx-for-ai.dev/mcp（OAuth サインイン）に接続し、すべてのツールの一覧を要求します。
バージョン 0.1.1 では、プラグインの .mcp.json 内のサーバーキーが xlsx-for-ai から spreadsheets に変更されました。そのため、/mcp には plugin:xlsx-for-ai:xlsx-for-ai ではなく、plugin:xlsx-for-ai:spreadsheets と表示されます。Claude Code はプラグイン独自の .mcp.json からキーを読み込みます。それ以外のものがこのキーを読み込むことはありません。バージョン 0.1.0 をお使いの場合は、サーバー名が変更されたため、更新後に一度サインインしてください。
機能：
- セッション開始時（起動、再開、クリア、圧縮）に短いテキストを表示し、xlsx-for-ai ツールが役立つ状況とその理由、Claude Code からファイルを渡す方法、およびすべてのツール名を伝えます。
- Shopify のエクスポートファイル（商品、在庫、コレクション、リダイレクト、メタフィールド）を
shopify_*ツールに送り、Shopify にインポートできるファイル（さらに Google、Amazon、eBay、UPS のフィードファイル）を作成します。ツールは渡されたファイルを処理してファイルを返します。結果のインポートはご自身で行ってください。 - スプレッドシートファイルを扱う際に適用される
spreadsheetsスキルを追加します。 - Claude Code をホスト型サーバーに接続します。
実行しないこと：エンジンは含まれていません。計算、解析、変換を行う当社のコードがマシン上で実行されることはありません。ローカルで実行されるのは、セッション開始時に cat がテキストファイルを表示する処理だけです。ツールに渡したファイルは、リンクまたは一度限りのアップロードによってホスト型サービスに送信されます。プラグインは claude-code-plugin/ にあります。セッション開始時のテキストは scripts/plugin/generate-session-start.js が claude-code-plugin/tool-manifest.json から生成し、両者の内容が一致しない場合はテストが失敗します。Windows では、フックは Git Bash または PowerShell で動作します（どちらでも cat を利用できます）。
機能
tools/list に登録されたツールは 52 個です。説明は意図的に詳しくしています。会話履歴を読むエージェントが、追加のドキュメントなしで各ツールの機能と使用する状況を把握できるようにしています。
トリアージ／概要把握
| ツール | 機能 |
|---|---|
xlsx_doctor | 1 回の呼び出しでブックの健全性をレポートします。 HIGH／MEDIUM／LOW の指摘事項（マクロ、外部リンク、非表示のシート、メタデータの欠落、大きな画像）に加え、基本情報と機能フラグを表示します。内容不明のブックで最初に呼び出すツールです。 |
xlsx_topology | 1 回の呼び出しでブックの概要を把握できます。シート、寸法、数式、名前付き範囲、テーブル、入力規則、ハイパーリンク、セル結合をまとめて確認できます。 |
xlsx_list_sheets | すべてのシート名とメタデータを一覧表示します。読み取り前の最初の確認に適しています。 |
xlsx_schema | シートごとに列の型、NULL 許容フラグ、ヘッダー行、サンプル値を推定します。 |
xlsx_describe | すべての数値列に対して Pandas 形式の .describe() を実行し、件数、平均、標準偏差、最小値、最大値、四分位数を表示します。 |
xlsx_workbook_views | UI の状態を表示します。固定ウィンドウ、ズーム、アクティブセル、非表示／完全非表示のシート、タブの色、アクティブなタブを確認できます。 |
xlsx_properties | ブックのメタデータを表示します。作成者、更新日時、会社、タイトル、カスタムドキュメントプロパティが含まれます。 |
読み取り／書き込み
| ツール | 機能 |
|---|---|
xlsx_read | ワークブックを読み取ります。テキスト、JSON、またはマークダウン形式に対応しています。数式、名前付き範囲、レイアウト、データ型は保持されます。IDを指定してライブの Google Sheet（source:"gsheets"）も読み取れます。読み取り専用で、指定する読み取り専用の Google OAuth トークンを使用します。 |
xlsx_read_handle | バイト列の代わりにサーバー側のハンドルを使って読み取ります。ワークブックのアップロードが済んでおり、再転送を避けたいセッションフロー向けです。 |
xlsx_write | 構造化された仕様からワークブックを作成または更新します。複数シート、数式、名前付き範囲、テーブル定義に対応しています。 |
xlsx_data_clean | データをその場で正規化します。空白の削除、型変換、行の重複排除、明らかな文字コードの乱れの修正に対応しています。クリーンアップしたコピーと変更ログを返します。名前を付けて保存する形式で、入力は変更しません。 |
xlsx_diff | 2つのワークブックのセマンティック差分を取得します。セル単位の差分、数式の変更、構造の変化を確認できます。出力は決定的です。 |
xlsx_redact | 共有前にワークブックから PII を削除します。サーバー側で検出し、削除済みのコピーと監査マニフェストを返します。 |
xlsx_convert | 25種類以上の入力形式と16種類の出力形式（csv、tsv、html、ods、xls、xlsb、dif、sylk、prn、txt、dbf、eth、json、markdown、xlsx など）に対応しています。xlsx、xls、csv、json の入力には互換エンジンへのフォールバックがありません。独自エンジンが処理を拒否した場合、型付きの 501 capability_gap エラーが発生します。 |
xlsx_validate | 健全性を検証します。サーバー独自の OOXML エンジンでワークブックを解析し、正常に読み込めるかどうかをシートごとの構造概要とともに報告します。 |
xlsx_session_set_validations | 同じセッションで後続の呼び出しに適用する検証ルールをセッションごとに設定します（例：必須列がない行を拒否する）。状態を保持し、このセッションにのみ適用されます。 |
Pandas と同等の機能（集計を新たに計算）
| ツール | 機能 |
|---|---|
xlsx_filter | 条件（列、演算子、値）で行をフィルタリングします。任意で列を選択し、条件に一致する行を返します。 |
xlsx_aggregate | グループ化して集計します（sum／count／mean／min／max／median／std）。 |
xlsx_sort | 列ごとに昇順／降順を指定して、複数列で並べ替えます。 |
xlsx_value_counts | 列の度数表を作成します（pandas の .value_counts()）。 |
xlsx_pivot | 生データからピボットテーブルを新たに計算します。pandas の pivot_table() と同じ形式です。 |
xlsx_eval | 自由形式の数式を評価するか、独自の再計算エンジンでセル参照を再計算します。サードパーティ製の数式エンジンは使用しません。未実装の関数を使った数式には、誤った値ではなく「まだサポートされていません」という正確なエラーを返します。 |
構造の保持 — これが強みです（pandas では読み込み時にすべて失われます）
| ツール | 機能 |
|---|---|
xlsx_named_ranges | すべての名前付き範囲を、スコープ、参照先、値のプレビューとともに一覧表示します。 |
xlsx_tables | Excel の ListObject（テーブル）を、列見出し、データ範囲、集計行とともに一覧表示します。 |
xlsx_formulas | ワークブック全体の数式をすべて出力します（セル、シート、数式テキスト、キャッシュされた値）。 |
xlsx_data_validations | セル単位の入力規則（ドロップダウン、数値／日付の範囲、テキストの長さ、カスタム設定）を一覧表示します。 |
xlsx_hyperlinks | ハイパーリンクを、種類の分類（外部／内部／mailto／不明）とともに一覧表示します。 |
xlsx_conditional_formats | 条件付き書式のルール（カラースケール、データバー、アイコンセット、数式に基づく強調表示、上位 N 件、重複）を一覧表示します。 |
xlsx_styles | 表示形式、フォント、塗りつぶし、配置を、シート単位でまとめるか、セルごとに詳細表示します。 |
xlsx_comments | 従来のメモとスレッド形式の会話の両方に対応します（複数の作成者に対応し、表示名も解決します）。 |
xlsx_protection | シートのロック、セルごとのロック／非表示フラグ、ワークブックの構造／ウィンドウのロックを確認します。 |
xlsx_merged_cells | レイアウトを考慮したセル結合の一覧を、マスター値と種類の推定（ヘッダー／横方向／縦方向／ブロック）とともに表示します。 |
xlsx_charts | グラフの仕様（種類、タイトル、系列の数式参照、軸タイトル）を確認します。多くのスプレッドシートライブラリが無視するグラフ XML パーツから直接読み取ります。 |
xlsx_images | 埋め込み画像の一覧（形式、サイズ、シート、アンカーセル）を表示します。 |
xlsx_pivot_tables | 既存のピボットテーブル定義（場所、ソース、集計関数付きの行／列／ページ／データフィールド）を確認します。 |
xlsx_slicers_timelines | Excel の最新のフィルター UI（テーブル／ピボットに紐づくスライサーと、選択範囲付きの日付範囲のタイムライン）を確認します。 |
xlsx_external_links | ワークブック間の参照を、リンク先の分類と、共有時にパスが切れる場合の警告とともに表示します。 |
xlsx_print_settings | 「Excel で印刷するとどうなるか」を確認します（印刷範囲、用紙サイズ、余白、ヘッダー／フッター、印刷タイトル）。 |
xlsx_form_controls | チェックボックス、ボタン、ドロップダウン、スピナー、スクロールバー、リストボックスなどのインタラクティブなウィジェットを、リンク先セルと範囲とともに確認します。 |
xlsx_macros | VBA マクロの有無、モジュール名の推定、安全に関するアドバイスを確認します（ポリシーによりソースは抽出しません）。 |
インテグレーション
| ツール | 機能 |
|---|---|
xlsx_post_slack | ワークブックをファイル添付として Slack チャンネルに投稿します。任意のメッセージも指定できます。BYOA — エージェントがユーザーの Slack ボットトークン（xoxb-…）を提供します。トークンは Slack に転送され、保存されることはありません。Slack の外部アップロードフローを使用します。 |
xlsx_post_teams | ワークブックを、チャンネルメッセージへのファイル添付として Microsoft Teams チャンネルに投稿します。任意のメッセージも指定できます。BYOA — エージェントがユーザーの Microsoft Graph アクセストークン（JWT）を提供します。トークンは Microsoft に転送され、保存されることはありません。Graph の filesFolder + upload-session + post-message フローを使用します。 |
整合性の検証
| ツール | 説明 |
|---|---|
xlsx_stamp | 暗号学的な「整合性検証」スタンプを使ってワークブックに署名します。Ed25519 で署名されたクレーム（名前付きの事実確認と、それぞれの合格／不合格／スキップの状態、およびコンテンツハッシュ）を docProps/custom.xml に埋め込みます。スタンプは保存後もファイルとともに保持されるため、受信者は後から検証して、署名後にファイルが改ざんされていないことを確認できます。事実に基づく証明のみを対象とし、意見に基づくお墨付きは決して行いません。 |
xlsx_verify_stamp | ワークブックに埋め込まれたスタンプを検証します。（a）登録済みの公開鍵に対して Ed25519 署名が有効かどうか、（b）ワークブックのバイト列が署名済みクレーム内のハッシュと一致するかどうか、（c）スタンプに含まれる確認結果の全内容を返します。署名の整合性、コンテンツの整合性、当初証明された内容という、3 つの異なる信頼シグナルです。 |
xlsx_receipt | AI 生成レシートを添付します。呼び出し元が申告したエージェント ID（名前、表示名、ID URL）、生成日時、コンテンツハッシュ、任意のソースファイルハッシュ、任意のプロンプトハッシュ、任意の呼び出し済み MCP ツール、および任意の説明を記述したクレームに、Ed25519 で署名します。重要な誠実性の境界として、サーバーが署名するのは呼び出し元が申告した agent.name です。呼び出し元が実際にそのエージェントであることは検証しません。暗号学的な ID の紐付け（エージェントごとに発行された署名鍵）は v1.1+ の対象です。 |
xlsx_verify_receipt | ワークブックに埋め込まれたレシートを検証します。xlsx_verify_stamp と同じ 3 つの信頼シグナルに加え、呼び出し元が申告したエージェント ID を申告どおりに返します（暗号学的な ID 検証を示唆する UI 表現はありません）。サーバーが呼び出し元の誠実な申告に署名したことを根拠として、「このファイルはどこから来たのか？」を示すために使用します。 |
ヒーラー — 外部参照の破損
ワークブックは劣化します。ファイルが移動すると、依存するすべての数式に #REF! が広がります。Power Query 接続には、誰も更新できない認証情報が埋め込まれていることがあります。定義名が、もう存在しない外部ワークブックを参照していることもあります。ヒーラーファミリーは、こうした問題の種類を診断し、対象を絞った修復を適用します。診断は読み取り専用で、修復は適用前にシミュレーションでき、エージェントが個別の修復操作を指定したくない場合には高レベルのインテントパスも利用できます。
| ツール | 説明 |
|---|---|
xlsx_healer_diagnose | 外部参照の破損に関する構造化レポートです。破損した外部参照、定義名の外部参照、認証情報が埋め込まれた Power Query 接続、#REF! の伝播マップ、複数ホップの連鎖を報告します。読み取り専用です。 |
xlsx_healer_simulate | 特定の修復操作を適用する前に、どのような変更が行われるかを表示します。形式は xlsx_healer_cure と同じですが、読み取り専用です。実行に進むべきかエージェントが判断できない場合に、影響を事前確認するために使用します。 |
xlsx_healer_cure | 特定の修復操作を 1 つ適用します（例：破損した外部参照の削除、定義名の統一、#REF! の伝播を決定論的な値に置き換えるなど）。Save-As 形式で処理されます。mode:"in_place" を指定して confirm:true を設定しない限り、ソースワークブックは保持されます。 |
xlsx_healer_intent | 高レベルのインテントパス（make-it-work、make-standalone、migrate）を、適切な修復操作の順序に変換します。目標は分かっていても、どの操作を行えばよいか分からないエージェント向けです。 |
ツールの応答には引用フッターと _meta ブロック（ツール名、バージョン、ティア、リクエスト ID、powered_by）が含まれます。どちらもそのまま引き継がれ、削除されることはありません。
ツール
MCP サーバーが公開する 52 個のツールすべて（tools/list から生成）を利用できます。エージェントに自然な英語で依頼するか、API／CLI を直接呼び出してください。
読み取りと探索
xlsx_read— パスで .xlsx ファイルを読み取り、レンダリングされた Markdown／JSON／SQL 表現を返します。ライブの Google Sheet も読み取れます。source:"gsheets"に加え、spreadsheet_idと読み取り専用の Google OAuth トークンを指定してください（トークンは注入方式です。読み取り専用で、書き込みはできません。サーバーが Google の認証情報を発行したり、仲介したりすることはありません）。同等の.xlsxを読み取った場合と同じ形式で出力します。xlsx_read_handle— 分割アップロードフローを通じてすでにサーバーにアップロードされているワークブックを、サーバー側のキャッシュハンドルで読み取ります。バイトデータを再転送する必要はありません。xlsx_readと同じ形式（text／json／markdown）を返しますが、file_b64 の往復は省略します。xlsx_validate— ローカルの .xlsx ファイルの整合性を確認します。サーバー独自の OOXML エンジンでワークブックを解析し、正常に読み込めるかどうかを報告します（ZIP の切り詰め、暗号化されたコンテナー、ワークシートがない場合、またはシート本文が破損している場合は、それぞれ失敗します）。シートごとの構造の概要も返します。
構造を確認する
-
xlsx_charts— ローカルの .xlsx ファイル内のすべてのグラフを、種類（bar / line / pie / scatter / area / doughnut / radar / stock / surface / bubble）、タイトル、軸タイトル、系列ごとの数式参照（グラフがデータを取得するセル範囲）とともに一覧表示します。シートの特定には OOXML の描画リレーションチェーンを使用します。 -
xlsx_comments— ブック内のすべてのセルコメントを一覧表示します。従来のメモ（黄色い付箋、cell.note）と、OOXML の zip 内に別途保存されている最新のスレッド形式コメント（複数の作成者による会話）の両方が対象です。各エントリには、種類、シート、セル、作成者、テキスト、および返信スレッドがあればその情報を含みます。 -
xlsx_conditional_formats— ブック内のすべての条件付き書式ルールを一覧表示します。カラースケール、データバー、アイコンセット、数式ベースのハイライト、上位 N 項目、重複値／一意の値、テキストを含む、期間、平均より上が対象です。各ルールには、範囲、種類、演算子、数式、優先度、stopIfTrue を含みます。 -
xlsx_data_validations— ブックで定義されている、セル単位のすべてのデータ入力規則（ドロップダウン、数値／日付の範囲、テキスト長の上限、カスタム数式）を一覧表示します。人がセルに入力するときに Excel が適用する制約です。 -
xlsx_describe— pandas 形式の df.describe() を列ごとに出力します。数値列については count、nulls、unique、min/max/mean/std、データ型と純度スコアを示します。 -
xlsx_external_links— このファイルが依存する外部ブックへの参照をすべて一覧表示します。=[Budget.xlsx]Sheet1!A1形式の数式が対象です。各リンクには、ターゲットパス（デコード済み）、分類（http / network share / absolute / relative）、外部ブックから参照されるシート、キャッシュされたセル値の数、定義名への参照を含みます。 -
xlsx_form_controls— ブック内のすべてのフォームコントロール（Check Box、Button、Drop-down、List Box、Option Button、Scroll Bar、Spinner、Label、Group Box）を、リンク先のセル、現在の値、ドロップダウンの参照範囲、該当する場合は最小値／最大値／ステップ幅とともに一覧表示します。 -
xlsx_formulas— ローカルの .xlsx ブック内のすべての数式を抽出します。セル座標（A1）、数式テキスト、キャッシュされた結果を含みます。openpyxl 形式の読み取り専用メタデータです。 -
xlsx_hyperlinks— ブック内のすべてのハイパーリンクを、アンカーセル、リンク先の URL／アンカー、表示テキスト、ツールチップ、種類の分類（external / internal / mailto / unknown）とともに一覧表示します。 -
xlsx_images— ローカルの .xlsx ファイルに埋め込まれたすべての画像を、形式（png / jpg / gif / svg / bmp / tiff / emf / wmf）、バイト単位のサイズ、シート、アンカーセル範囲（画像が重なっているセル）とともに一覧表示します。xl/media/* と xl/drawings/* を直接読み取ります。 -
xlsx_list_sheets— ローカルの .xlsx ファイルのシート名、サイズ、表示状態を一覧表示します。 -
xlsx_macros— xlsm / xlsb ブックを検査し、VBA マクロの有無、vbaProject.bin のサイズ、モジュール名の候補（ThisWorkbook / Sheet / Module / Class / UserForm。UTF-16LE のヒューリスティックなスキャンによる）を示します。LLM がユーザーに伝えるべき簡潔な安全上のアドバイスも返します。 -
xlsx_merged_cells— すべての結合セル領域を、マスターセルの値、範囲、縦横の寸法、種類の推定値（"header" / "horizontal" / "vertical" / "block"）とともに一覧表示します。Pandas は結合セル間の関係を破棄して読み込むため、マスターセルの値を1つ読み取り、隣接する3つのセルを空欄として扱います。xlsx_merged_cells はレイアウトを考慮した表示を提供します。「A1:D1 は Q4 2024 と書かれた1つのセル」であり、「3つがなぜか空欄になっている4つのセル」ではありません。 -
xlsx_named_ranges— ローカルの .xlsx ブック内で定義されているすべての名前（名前付き範囲）を一覧表示します。名前、スコープ（ブックまたはシート）、種類（セル／範囲／数式）、参照先を含みます。 -
xlsx_pivot_tables— ローカルの .xlsx ファイル内にすでに存在するすべてのピボットテーブル定義（Excel ユーザーがすでに作成したもの）を一覧表示します。各ピボットテーブルには、シート、名前、場所の範囲、ソース範囲（または名前付き範囲／テーブル参照）、行／列／ページフィールド、集計関数（sum / count / average / max / min / product / stdDev など）を含むデータフィールドを示します。 -
xlsx_print_settings— ワークシートごとに「Excel で今印刷するとどうなるか」を表示します。印刷範囲、向き、用紙サイズ（A4 / Letter / Legal / Tabloid など）、倍率または fitToPage、余白、Excel の L/C/R ゾーンに分けたヘッダー／フッター、印刷タイトル（各ページに繰り返す行／列）、手動改ページに加え、白黒／ドラフト／中央配置の各フラグを含みます。 -
xlsx_properties— ローカルの .xlsx ファイルに含まれるブックの識別情報を表示します。基本情報：作成者、最終更新者、作成／変更／最終印刷の日時、タイトル、件名、会社、管理者、キーワード、カテゴリ、説明。アプリケーション情報：アプリ名とバージョン、ドキュメントのセキュリティラベル、ハイパーリンクのベース。カスタム情報：ユーザーが定義した「情報 > プロパティ」のすべての項目（Department、ReviewedBy、ApprovalRequired など）と、種類タグおよび値。 -
xlsx_protection— ローカルの .xlsx ファイルに含まれるすべての保護設定を表示し、エージェントが編集できる内容とできない内容を判断できるようにします。ブックレベル（lockStructure、lockWindows）、シートごと（保護の有無、パスワード、表示状態）、操作ごとの許可／禁止一覧（formatCells、sort、insertRows、pivotTables など）、およびロック解除／非表示のセルのサンプルを含みます。これらは、シートがそれ以外の点では読み取り専用の場合に、人が実際に入力できるセルです。 -
xlsx_schema— ローカルの .xlsx ファイルの列スキーマ（型、null 許容フラグ、ヘッダー行、サンプル値）を推定します。 -
xlsx_slicers_timelines— ローカルの .xlsx ファイル内のすべてのスライサー（対話型フィルターボタン）とタイムライン（日付範囲の視覚的フィルター）を、キャプション、ソースの関連付け（テーブル列またはピボットテーブル）、タイムラインの粒度（年／四半期／月／日）、現在選択されている日付範囲とともに一覧表示します。 -
xlsx_styles— セルの書式（表示形式、フォント、塗りつぶし、配置）を表示し、エージェントが生の値だけでなく、セルの見た目も把握できるようにします。デフォルトモードでは、シートごとに上位 N 件の表示形式／フォント／塗りつぶしを件数とともにまとめます。詳細モード（オプトイン、最大 1000 セル）では、絞り込んだクエリ向けにセルごとの内訳を表示します。 -
xlsx_tables— ローカルの .xlsx ブック内のすべての Excel ListObject（「テーブルとして書式設定」の構造）を、名前、シート、範囲、ヘッダー／集計行のフラグ、列とともに一覧表示します。 -
xlsx_workbook_views— ローカルの .xlsx ファイルの UI 状態（Excel で開いたときに人が見る状態）を表示します。シートごとに、表示状態（表示／非表示／非常に非表示）、ビューの状態、ズーム、アクティブセルと選択範囲、ウィンドウ枠の固定の内訳、目盛線／行列見出し／ルーラー／RTL の各フラグ、シートタブの色を示します。ブックレベルでは、Excel を開いたときにアクティブになるシートを示します。 クエリと分析 -
xlsx_aggregate— ローカルの .xlsx ファイルに対して、pandas 形式の df.groupby([cols]).agg({col: func}) を実行します。使用できる関数：sum / mean / min / max / count / count_distinct。 -
xlsx_diff— 2 つのローカルの .xlsx ファイル間のセマンティック差分を計算します。セルレベルの差分、数式の変更、追加・削除された行を確認できます。 -
xlsx_eval— 独自の再計算エンジンを使って、ローカルの .xlsx ファイル内の Excel 数式を評価します。xlwings 形式です。 -
xlsx_filter— ローカルの .xlsx ファイルに対して、pandas 形式の行フィルターを実行します。述語は AND で結合されます：eq/ne/gt/gte/lt/lte/contains/in/is_null/not_null。 -
xlsx_pivot— ローカルの .xlsx ファイルに対して、pandas 形式の pivot_table() を実行します。フラットなテーブルを、indexの一意の値を行、columnsの一意の値を列とし、セルにvaluesの集計値を配置した 2D マトリックスに変換します。 -
xlsx_sort— ローカルの .xlsx ファイルに対して、pandas 形式の df.sort_values() を実行します。複数列での並べ替えと、列ごとの昇順・降順（asc/desc、デフォルトは asc）に対応します。 -
xlsx_topology— ワークブックの構成を 1 回の呼び出しで把握できます。シート × 寸法 × 数式 × 名前付き範囲 × テーブル × 入力規則 × ハイパーリンク × 結合セルをまとめて返し、さらに機能フラグ（マクロ／外部参照／ピボット／LAMBDA／動的配列）も返します。 -
xlsx_value_counts— ローカルの .xlsx ファイル内の 1 列に対して、pandas 形式の Series.value_counts() を実行します。一意の値ごとに件数を数え、頻度の降順で並べ替え、割合も表示します。
クリーンアップと修正
xlsx_data_clean— ローカルの .xlsx ファイル向けの AI ネイティブなデータクレンジングツールです。よくある 7 種類のデータの汚れをスキャンします。NA の表記ゆれ（N/A、NA、null、-）、結合セルの残骸、型変換の誤り（数値がテキストとして保存されている／日付がシリアル値になっている／先頭のゼロが削除されている）、末尾行のノイズ（フッター／合計）、ヘッダー行が先頭にない（ヘッダー前の前置きテキスト）、文字コードの不具合（UTF-8 を CP1252 として解釈した文字化け）、列ヘッダーの重複です。問題を検出するだけの診断モード、または決定的な修正を適用する実行モードを選べます。
変換
xlsx_convert— 汎用のスプレッドシート形式コンバーターです。25 種類以上の入力形式（xlsx、xlsb、xlsm、xls、ods、fods、numbers、csv、tsv、dbf、lotus 1-2-3、quattro pro、sylk、dif、html、rtf など）を読み込み、対応する任意の出力形式（xlsx、csv、json、md、html など）で出力します。
書き込み（新規ファイル）
xlsx_redact— 共有またはアーカイブする前に、ローカルの .xlsx ファイルから個人情報や機密性の高い値を墨消しします。xlsx_write— 構造化された仕様に基づいて、ローカルの .xlsx ファイルを作成または更新します。
整合性と検証
xlsx_healer_cure— 診断済みのワークブックに、特定の修復操作を1つ適用します。操作：rename_move（参照パスを書き換える）、pattern_bulk（正規表現形式で参照を書き換える）、source_deleted_freeze（壊れた参照をキャッシュ値に置き換える）、source_deleted_redirect（置換ファイルを参照するようにする）、source_deleted_localize（外部ソースをローカルコピーにスナップショットする）、permission_denied（認証情報を削除する）、structure_changed（移動したセルに合わせて数式を書き換える）、format_change（拡張子の変更後に再リンクする）、make_standalone（すべての外部参照を完全に解決する）。修復済みワークブックのバイトデータとレシートを返します。xlsx_healer_diagnose— ワークブック内で壊れている、または問題が発生する可能性のある外部参照の構造化された診断レポートを生成します。5種類の検出結果を返します：（1）解決できない外部ワークブック参照、（2）定義名に含まれる外部参照、（3）認証情報が埋め込まれた Power Query 接続、（4）上流の破損に起因する #REF! の伝播マップ、（5）複数段の参照チェーン（ワークブック → ワークブック → ワークブック）。検出結果には、後続の修復操作で使用する reference_id キーが含まれます。xlsx_healer_intent— 目標に基づいて修復します。呼び出し元は特定の修復操作ではなく、INTENT（make-it-work、make-standalone、またはmigrate）を指定します。Healer が操作の順序を計画し、適用します。make-it-work：エラーを解消するための最小限の変更を行います。make-standalone：外部依存関係をすべてスナップショットして、完全に外部参照を排除します。migrate：from/to のプレフィックスペアに基づいて、すべての参照を書き換えます。計画した操作、修復済みのバイトデータ、および実行不能な項目の一覧を返します。xlsx_healer_simulate— ワークブックの外部参照が受信者側からアクセス可能かどうかをシミュレーションします。受信者が参照できるパスのリスト（accessible_paths）を指定すると、受信者側で解決できる参照と、解決できない参照（およびその理由）を返します。読み取り専用で、出力ワークブックは生成しません。xlsx_receipt— ローカルの .xlsx ファイルに AI 生成レシートを添付します。docProps/custom.xml に埋め込まれる暗号学的な証明で、「このファイルは、THIS エージェントが THIS 時刻に THESE 入力を基に生成した」と記録します。レシート付きワークブックを _meta.file_b64 の Base64 形式で返します。ディスクに書き込むには out_path を渡してください。xlsx_stamp— ローカルの .xlsx ファイルに「ワークブック整合性検証」スタンプを署名します。docProps/custom.xml に埋め込まれる暗号学的な証明で、「このファイルはこれらのツールで生成され、指定された N 個の検査に合格し、この時刻に署名され、その後改ざんされていない」と記録します。事実に基づく主張のみを記載し、意見に基づくお墨付きは付与しません。スタンプ付きワークブックを _meta.file_b64 の Base64 形式で返します。ディスクに書き込むには out_path を渡してください。xlsx_verify_receipt— ワークブックに埋め込まれた AI 生成レシートを検証します。署名が有効か、再計算したコンテンツハッシュがレシート内のハッシュと一致するか、呼び出し元が宣言したすべての情報（エージェントの識別情報、生成日時、ソースファイルのハッシュ、プロンプトのハッシュ、呼び出された MCP ツール、説明）を返します。xlsx_verify_stamp— ワークブックに埋め込まれた整合性検証スタンプを検証します。暗号学的署名が有効か、ワークブックのバイトデータが署名された内容と一致するか（再計算したハッシュとスタンプ内のハッシュを比較）、スタンプの検査結果の内容全体を返します。
連携
xlsx_post_slack— ローカルの .xlsx ファイルを、ファイル添付として Slack チャンネルにアップロードします。任意のメッセージを添えることもできます。xlsx_post_teams— ローカルの .xlsx ファイルを、ファイル添付として Microsoft Teams チャンネルにアップロードします。任意のメッセージを添えることもできます。
セッション
xlsx_session_set_validations— 同じセッション内で後続の呼び出しにサーバーが適用する、セッション単位のデータ検証ルールを設定します（例：必須列が欠けている行を拒否する、カテゴリ列の列挙値を強制する、数値入力を範囲内に制限する）。状態を保持し、このセッションにのみ影響します。
1回の呼び出しで完結する総仕上げ
xlsx_doctor— ローカルの .xlsx ファイルのブック状態を1回の呼び出しでレポートします。マクロ、外部ブック参照、非表示／veryHidden シート、作成者メタデータの欠落、大きな埋め込み画像をスキャンし、興味深い機能フラグ（LAMBDA、動的配列、ピボットキャッシュ、スライサー、スレッド形式のコメント）を提示します。検出結果は HIGH／MEDIUM／LOW でランク付けされます。さらに、シート数、数式、名前付き範囲、結合セル、ハイパーリンク、入力規則、画像、ファイルサイズを含む quick_facts も提供します。
関数
xlsx_eval は独自の再計算エンジンで数式を再計算します。現在、350 を超える Excel 関数に加えて、Google Sheets だけで使える関数も計算でき、実装に合わせて対応関数を追加しています。対応範囲は、標準的な関数ファミリーである数学・三角関数、統計、財務、日付と時刻、文字列、論理、検索と参照、情報、エンジニアリングにわたります。提供している関数の全リストは、https://xlsx-for-ai.dev の Functions セクションにあります。
エンジンがまだ提供していない関数は、推測した値ではなく、正直に「まだサポートされていません」というエラーを返します。WEBSERVICE、RTD、STOCKHISTORY など、ブック外にアクセスする関数は提供していないため、再計算でブック外にアクセスすることはありません。
FP&A ワークフロー
xlsx-for-ai は、実際の財務スプレッドシートを扱うエージェント向けに構築されています。一般的なワークフローは次のとおりです。
予算と実績の差異分析
xlsx_read → extract actuals and budget → agent computes variances → xlsx_write → deliver updated workbook
月次決算の照合
xlsx_read (bank export) + xlsx_read (GL extract) → agent matches rows → xlsx_diff → audit trail of unmatched items
監査証跡の抽出
xlsx_schema → identify change-log columns → xlsx_read with sheet filter → agent summarizes changes by author/date
複数事業体の連結
xlsx_read × N entity files → agent aggregates → xlsx_write → consolidated workbook with intercompany eliminations noted
共有前の PII マスキング
xlsx_redact → strips SSNs, emails, employee IDs → redacted file safe for external distribution
こうしたワークフローがあるため、ツールの説明は FP&A の観点で理解しやすくなっています。開発者が財務チーム向けのエージェントを構築する際、エージェントの LLM はツールの説明を読み取り、追加のプロンプトエンジニアリングなしで適切に振り分けます。
信頼性機能
- 決定論的な差分。
xlsx_diffは同一の入力に対して常に同一の出力を生成するため、安全にバージョン管理でき、CI での比較にも適しています。 - 信頼度付きのスキーマ推論。
xlsx_schemaは推論した型とともに型の信頼度スコアを返します。エージェントは盲目的な推測を信頼するのではなく、信頼度に基づいて処理を分岐できます。 - 監査証跡。 成功・失敗を問わず、すべてのツール呼び出しがタイムスタンプ、クライアント ID、エンドポイント、ファイルサイズ、レイテンシ、エラークラスとともにサーバー側で記録されます。
- 強化された入力検証。 アップロードされたバッファーごとに、エンジン処理前の4つのガードが適用されます。ビリオン・ラフ攻撃を引き起こす XML 爆弾への防御、制御文字の除去、ワークシートバッファーの上限設定（低速な ZIP 爆弾への防御）、型付きエラーの連鎖です。xlsx エンジンがバイト列を受け取る前に適用されます。
- エージェントが読み取れるエラー。 レート制限エラーと検証エラーは構造化 JSON で返されます。エージェントはステータスコードを表示するだけでなく、エラーを読み取り、ユーザーに適切にプロンプトを提示できます。
プライバシー
ファイルは HTTPS 経由で https://api.xlsx-for-ai.dev に送信され、メモリ上で処理されます。ファイルは1回のリクエストの処理時間を超えて保存されません。Google アカウントでサインインします。メールアドレスはアカウントの識別にのみ使用され、パスワードは保存されません。
データの取り扱いに関するポリシーの全文は、PRIVACY.md をご覧ください。
料金
すべてのツールが含まれています。初回利用時に一度サインインします（エディターに表示されるリンクとコード、またはターミナルで xlsx-for-ai login を実行）。登録者のうち先着1,000人は、毎月500ファイルを無料で利用できます。それ以降のユーザーは、無料で10ファイルを利用した後、年間25ドルで毎月10,000ファイルを利用できます。サインインには Google を使用します。ファイルサイズの上限はどのプランでも同じです。.xlsx は最大100 MB、.xls は最大100 MB、.csv は最大200 MBです。上限に達すると、サービスからのメッセージにこれらの上限が表示されます。
ライセンス
npm クライアント（xlsx-for-ai、本パッケージ）は MIT ライセンスです。ホスト型 API サーバー（xlsx-for-ai-server）はプロプライエタリです。エンジンの知的財産、レンダリングパイプライン、セマンティック差分アルゴリズムはオープンソースではありません。
アーキテクチャ
agent (Claude Code / Claude Desktop / Cursor / Continue / Zed / Windsurf / custom)
└── MCP stdio
└── xlsx-for-ai-mcp (this package, ~200 lines)
└── POST /api/v1/tools/<name> → api.xlsx-for-ai.dev
└── server-side engine (own OOXML/CSV engine, formula eval, schema inference, redaction)
要件： Node.js 22 以降。アップグレードできないユーザー向けに、1.5.x 系は main で保守を継続します。
初回実行時のサインイン
xlsx-for-ai login
リンクと短いコードを表示します。任意のブラウザーでリンクを開き、Google でサインインして承認すると、CLI がキーを ~/.xlsx-for-ai/config.json に保存します。キーが保存されていない状態で、対話型ターミナルからいずれかのコマンドを実行すると、同じ手順が自動的に始まります。もう一度サインインするには、xlsx-for-ai login --force を実行します。
エディターやデスクトップアプリから使う場合（ターミナルなし）。 最初に何かを実行しておく必要はありません。初めてアシスタントにスプレッドシートのツールを使うよう頼むと、回答の代わりにサインインリンクと短いコードが返されます。ブラウザーでリンクを開き、コードが一致していることを確認して承認してください。その後、もう一度依頼すると、再起動せずにリクエストが実行されます。承認前にもう一度依頼した場合は、同じリンクとコードが表示されます。リンクの有効期限が切れた場合（約 15 分）、または承認しなかった場合は、次のリクエストで新しいリンクが表示されます。
応答する画面のないターミナルコマンド（たとえば、スクリプトや別のプログラムから実行されたコマンド）。コマンドはリンクとコードをエラー出力に表示し、承認されるまで最大 60 秒待機します。時間内に承認すると、リクエストの処理が続行されます。承認しなかった場合は処理を停止し、承認してから同じコマンドをもう一度実行するよう通知します。2 回目の実行では同じコードが使われるため、新たにコピーする必要はありません。その間に承認が済んでいれば、すぐに完了します。待機時間を変更するには、XFA_LOGIN_WAIT_SECONDS を設定します（たとえば XFA_LOGIN_WAIT_SECONDS=120）。
自動実行（CI）や、XFA_NONINTERACTIVE=1 を設定した実行では、待機もサインインの開始も行われません。キーがない場合、コマンドはすぐに停止してその旨を通知します。自動実行では、ターミナルのあるコンピューターで一度サインインし、~/.xlsx-for-ai/config.json の api_key の値を環境変数 XLSX_FOR_AI_KEY として実行環境に渡してください（シークレットストアに保管してください）。この環境変数と保存済みファイルの両方がある場合は、環境変数が優先されます。
保存済みのキーが拒否された場合。 エディターやデスクトップアプリでは、次のリクエストに新しいサインインリンクが表示されます。新しいキーを承認するまでは、保存済みのキーはそのまま維持されます。ターミナルでは、xlsx-for-ai login --force を実行してください。
表示される可能性のあるメッセージ。 使用制限に達した場合、そのメッセージはサービス自体から返されます。402 ではメッセージとアップグレード用リンクが、429 ではメッセージと再試行できる時期が表示されます。501 は、その機能がまだ実装されていないことを示します。ファイルに問題はなく、再試行しても解決しません。この場合、ターミナルコマンドは終了コード 5 で終了します（3 はサービスに接続できなかったか、サービスに障害があった場合、4 はファイルまたはリンクに問題がある場合、2 は使用方法に誤りがある場合、1 はそれ以外の場合です）。
更新。 読み取り専用のインストール環境やコンテナーなど、このコピーが自己更新できない場合、ツールの結果に新しいバージョンがあることと更新コマンドが表示されます。コマンドを実行できるアシスタントがあれば、代わりに更新できます。そうでない場合は、ターミナルで npm install -g xlsx-for-ai@latest を実行して、アプリを再起動してください。XFA_NO_AUTO_UPDATE=1 を設定すると、自己更新とこの通知を無効にできます。
リンクはファイルではありません。 このパッケージが読み取るのは、コンピューターに保存されたファイルのみです。ファイルパスの代わりにウェブリンクや Google Sheets のリンクを指定すると、その旨が通知されます。ファイルをダウンロードしてパスを指定するか、リンクを直接開けるホスト型の xlsx-for-ai コネクターを使用してください。
Docker での実行。 イメージはサインインをスキップしなくなりました。最初のリクエストでサインインリンクとコードが表示されます。キーはコンテナー内の /home/node/.xlsx-for-ai に保存されるため、実行間で保持するには、たとえば -v xfa-config:/home/node/.xlsx-for-ai のようにボリュームをマウントしてください。
4.1.0 より前のバージョンで発行されたキーは、現在も引き続き使用できます。サービスがキーの停止予定を示した場合、ツールの結果にその旨がわかりやすく表示されます。ここでは日付は提示されません。
設定
~/.xlsx-for-ai/config.json に保存されます。初回実行時に自動的に作成されます。その隣にある pending-login.json には、サインインを開始して承認待ちになっている情報が保存されます（再実行すると同じコードが表示されます）。サインインが完了するか、コードの有効期限が切れると削除されます。フォルダーは XFA_CONFIG_DIR で移動できます。
{
"client_id": "<uuid>",
"api_key": "<opaque>",
"registered_at": "2026-05-05T00:00:00.000Z",
"telemetry": false,
"consent_version": 1
}
テレメトリーはオプトインです。
xlsx-for-ai --enable-telemetry
xlsx-for-ai --disable-telemetry
xlsx-for-ai --telemetry-status
プライバシーモード — 2026-10-14 以降、すべてのアカウントでワークブックのキャプチャは無効です。XFA_PRIVACY=strict にすると、ツールが生成したファイルの60分間のダウンロード用コピーも無効になります。PRIVACY.md を参照してください。
# Per-session flag (applies to all tool calls in the CLI invocation)
xlsx-for-ai --privacy=strict myfile.xlsx
# Environment variable (applies globally to all requests in the process)
XFA_PRIVACY=strict xlsx-for-ai myfile.xlsx
# In MCP server config (applies to all tool calls from the MCP server):
# Set XFA_PRIVACY=strict in your MCP server's env block
クライアント ID と API キーをリセットするには、設定ファイルを削除してください。
rm ~/.xlsx-for-ai/config.json
1.5.x からの移行
| 以前 | 現在 |
|---|---|
| すべてのレンダリングがローカル | すべてのレンダリングがサーバー側 |
xlsx-for-ai <file> CLI | 同じ — 引き続き動作します |
cursor-reads-xlsx | 引き続き動作します — 下位互換性のための別名 |
--list-sheets、--schema、--diff など | MCP ツール（xlsx_list_sheets、xlsx_schema、xlsx_diff）に移行 |
--export-redacted-workbook | MCP ツール xlsx_redact に移行 |
| 大容量の npm インストール（約50 MB） | 軽量インストール（約2 MB）。エンジンはサーバー側に残ります |
| PII 検出、領域スコアリング | サーバー側に移行。npm パッケージでは公開されません |
~/.xlsx-for-ai/config.json の設定ファイルはその場で拡張され、既存のテレメトリーへの同意は保持されます。
セキュリティ
SECURITY.md を参照してください。すべてのファイル内容は HTTPS 経由で https://api.xlsx-for-ai.dev に送信されます。ファイルは単一のリクエストの処理期間を超えて保持されることはありません。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。