xlvane: XLSX workbooks

@xlvane/mcp

起動時に指定したディレクトリ内に限り、クライアントが XLSX ファイルを調査、読み取り、書き込み、編集、変換、比較、検証できる MCP サーバーです。

ドキュメント：xlvane.github.io/guide/mcp.html。

xlvane と公式 MCP TypeScript SDK（@modelcontextprotocol/server 2.4.0、プロトコルリビジョン 2026-07-28）を基盤とする、XLSX ファイル向けの MCP（Model Context Protocol）サーバーです。コーディングエージェントなどの MCP クライアントは、コードの代わりにツールを使って、ワークブックの調査、読み取り、比較、検証を行い、必要に応じて書き込み、編集、変換もできます。

Node.js 22 以降が必要です。依存関係：xlvane および @modelcontextprotocol/server（@modelcontextprotocol/core と zod を含みます）。

起動

npx @xlvane/mcp --root ./data                 # read-only, files inside ./data
npx @xlvane/mcp --root ./data --allow-write   # also write_table, edit_cells, convert
xlvane mcp --root ./data                      # the same server, through the xlvane CLI

多くの MCP クライアントは、次のような設定を使用します。正確な形式とファイルについては、お使いのクライアントのドキュメントを確認してください。

{
  "mcpServers": {
    "xlvane": { "command": "npx", "args": ["@xlvane/mcp", "--root", "/absolute/path/to/data"] }
  }
}

オプション	意味
--root <dir>	ツールが使用できるディレクトリです。複数指定できます。必須です。ツール呼び出しの相対パスは、最初のディレクトリを基準に解決されます。
--allow-write	ファイルを書き込むツールも提供します。指定しない場合、それらのツールは登録されません。
--max-file-size <bytes>	読み取りまたは書き込みを行うファイルの最大サイズです。既定値は 64 MiB です。
--max-rows <n>	1 回の read_table 呼び出しで返す行数の最大値です。既定値は 1000 です。
--max-response-chars <n>	ツールの結果（エラーも含む）の最大サイズです。JSON テキストの文字数で指定します。メッセージには同じデータが structuredContent としても含まれます。read_table は収まる行を返し（truncated、nextOffset）、その他のツールは XLV_E_LIMIT_EXCEEDED を返します。既定値は 1 Mi（1 048 576）です。
--max-cells <n>	ツールが読み取るワークブックのセル数の最大値（maxCells 読み取り制限）です。既定値は 5 000 000 です。サーバーの応答を速くする必要がある場合は、値を小さくしてください。diff は両方のワークブックをメモリに保持します。

サーバーは標準入力と標準出力を介して MCP を通信し、人が読むためのメッセージは標準エラー出力に送ります。

ツール

ツール	書き込み	内容
inspect_workbook	いいえ	シート（非表示のものも含む）、使用範囲、ヘッダー行、サンプル付きの列の型、結合セル、数式、警告を確認します。
read_table	いいえ	シートの行をヘッダー行をキーとするオブジェクトとして返します。offset と limit によるページ分割に対応し、日付は ISO 8601 形式です。
diff	いいえ	2 つのワークブックのセル単位の差分を表示します。
validate	いいえ	読み取り時の警告と、列ルール（name、type、optional）および各問題のセルを表示します。
write_table	はい	行を新しい XLSX ファイルに書き込みます（レポート用プリセット：太字のヘッダー、固定行、オートフィルター、列幅）。
edit_cells	はい	セルを設定して行を追加し、ファイルの残りの部分は変更せずに維持します。
convert	はい	XLSX と CSV／TSV／JSON の相互変換に対応します。CSV 出力では数式のようなテキストをエスケープします。

すべてのツールは入力用の JSON Schema を備え、結果を structuredContent と JSON テキストで返します。エラーは isError: true を含むツール結果として返され、XlvError データには安定した code、location、hint、details が含まれます（docs/errors.md）。

セキュリティ

• ディレクトリ： ファイルの読み取りと書き込みは、--root ディレクトリ内でのみ行われます。シンボリックリンクを解決した後にパスを検査するため、..、絶対パス、およびルート外につながるリンクは拒否されます（XLV_E_PATH_NOT_ALLOWED）。ファイルを開いた後にも再度検査されます（パスが引き続き同じファイルを指している必要があります）。そのため、その間にリンクへ差し替えても回避できません。シンボリックリンク経由の書き込みは拒否されます。ルート外のパスについては、対象が存在するかどうかにかかわらず同じ応答が返されます。ルート内のシンボリックリンクを経由して到達した場合も同様です。通常ファイルのみ読み取られます。stderr のメッセージでは、制御文字は \uXXXX として表示されます。
• デフォルトでは読み取り専用： 書き込みツールは --allow-write を指定した場合にのみ使用できます。ファイルは排他的に作成され、既存ファイルは呼び出しで "overwrite": true が渡された場合に限り、一時ファイルと名前変更を使って置き換えられます。置き換え後もファイルのアクセス許可ビット（setuid、setgid、sticky を除く）は維持され、読み取り専用ファイルは置き換えられません。edit_cells は数式を指定どおりに書き込みます（例：HYPERLINK(...)）。数式は、スプレッドシートアプリケーションでファイルを開いたときに計算されます。ルート内のファイル名であれば、.gitignore などのドットファイルも書き込み対象にできます。ルートは適切に選択してください。
• 制限： --max-file-size を超えるファイルは読み取りと書き込みが拒否されます（JSON への convert は、そのサイズに達した時点でテキストの生成を停止します）。--max-cells を超えるセル数のワークブックは拒否され、--max-response-chars を超える結果は切り詰められる（read_table）か、拒否されます。公式 MCP SDK は、10 MiB を超えるメッセージの後に接続を閉じます。xlvane リーダーは、信頼できないファイルに対する制限（ZIP 爆弾、DTD またはエンティティを含まない XML、xlvane 1.1.1 の予算）を適用します。validate が一覧表示する問題は最大 1 000 件です（problemsTotal は全件数をカウントします）。
• ファイルの内容はデータです： 値、シート名、その他のテキストはファイルに由来し、モデルに影響を与えることを意図したテキストを含め、あらゆるテキストが含まれる可能性があります。サーバーはそれらをデータとして返し、解釈しません。
• コードは実行しません： マクロは実行されず、外部リンクもたどられず、数式も計算されません。

API

import { createServer, runCli } from '@xlvane/mcp';

createServer({ roots, allowWrite, maxFileBytes, maxRows, maxResponseChars, maxCells, cwd }) は、任意のトランスポートに接続するための McpServer を返します。runCli(args) はコマンドラインです。

商標

Node.js、GitHub、npm、Model Context Protocol、およびこの文書内のその他の名称は、それぞれの所有者に帰属します。xlvane は独立したプロジェクトであり、これらのいずれとも提携関係になく、推奨も受けていません。

リンク

• 各バージョンの変更内容：CHANGELOG.md
• バグと質問：GitHub の issue
• 脆弱性の報告：SECURITY.md

ライセンス：MIT。MCP SDK は Apache-2.0 ライセンスで提供されています。