Sezzlee Excel

@sezzlee/excel-mcp

エージェント向けにローカルの Excel ファイルを読み取る、スタンドアロンの MCP サーバーです。書き込み機能はありません。

.xlsx、.xlsm、.csv を読み取り、アクセスは 1 つのフォルダー内に制限されます。サンドボックス機能、ドキュメントキャッシュ、エラーエンベロープ、カーソルコーデック、ツール登録レイヤーは @sezzlee/file-core に由来します。

ドキュメント：https://docs.sezzlee.app/docs/excel-mcp/introduction — チュートリアル、タスクガイド、このパッケージから生成されたツール、エラーコード、制限のリファレンスです。

クイックスタート

サーバーには、読み取りを許可するフォルダーの絶対パスを唯一の引数として指定します。そのフォルダー外は読み取れません。

{
  "mcpServers": {
    "excel": {
      "command": "npx",
      "args": ["-y", "@sezzlee/excel-mcp", "/Users/me/sheets"]
    }
  }
}

Claude Code の場合：

claude mcp add excel -- npx -y @sezzlee/excel-mcp /Users/me/sheets

macOS（x64、arm64）、glibc Linux（x64、arm64）、または Windows x64 では Node.js 22 または 24 が必要です。ファイルアクセスにはネイティブモジュールを使用し、JavaScript によるフォールバックはありません。

ツール

ツール	機能
list_workbooks	ルートフォルダー内の読み取り可能なファイルを一覧表示します。返される filePath は、他のツールにそのまま渡します
describe_workbook	シートとその種類（ワークシートまたはチャートシート）、使用範囲、結合、入力規則、テーブル、数式、画像、グラフの件数、定義名
profile_sheet	再利用可能な列仕様を含む、範囲を限定した型および品質プロファイル
read_sheet	セル範囲をコンパクトなグリッドとして返します。列ヘッダーを先頭にまとめ、行を配列で示します
aggregate_sheet	グループ別の集計、カレンダーおよび数値のバケット、範囲を限定したピボット、条件付き指標、正確なパーセンタイル
find_in_sheet	値または数式が検索クエリに一致するセル
get_tables	Excel テーブル：範囲、ヘッダー行と集計行、列名と列記号
get_data_validations	入力規則を長方形の範囲ごとにまとめて返します
get_conditional_formats	条件付き書式ルールを述語として返します
get_merged_ranges	結合セルの範囲
get_images	図形およびセル内の画像：アンカー、代替テキスト、サイズ、拡張子。グラフは get_charts で取得します
get_charts	グラフ：種類、タイトル、軸（第 2 軸、尺度、書式を含む）、系列参照／ポイント、近似曲線、非表示の系列、ピボットソース。チャートシートも含みます

すべての引数、エラーコード、制限はリファレンスに記載されています。

テキストが数値や日付として読み取られる方法

CSV にはテキストしか格納されず、ワークブックでも数値や日付がテキストとして保存されている場合があります。read_sheet とデフォルトの find_in_sheet は、そのテキストを記載どおりに返します。aggregate_sheet は、メトリックまたは where のオペランドで数値や日付が必要な場合に限り、値を数値または日付として読み取ります。さらに、範囲内のすべての値から列ごとに形式を判定します。判定対象は、小数点と桁区切りの記号（1.234,50、1,234.50、1 234,50、1'234.50）と、スラッシュ形式の日付で日と月のどちらが先にくるかです。より多くの値を読み取れる記号または順序が採用されます。採用された形式で値によって読み取り結果が異なる場合（1.234、01/02/2023）、その列は曖昧と判定され、該当する値は読み取られません。どの columns エントリで曖昧さを解消できるかは、警告に示されます。会計表記の括弧、先頭または末尾の %（比率として読み取り）、通貨記号または通貨コードは認識されます。ドット区切りの日付は日が先と解釈され、トルコ語と英語の月名も読み取られます。

先頭にゼロが付く、または15桁を超える数字の並びは識別子として扱われ、columns でその列を数値として指定しない限り合計されません。金額に複数の通貨が記載されている列は、記載どおりに合計され、その旨が報告されます。呼び出しで読み取り、比較、または合計できなかった値はすべて、例とともに warnings にカウントされます。また、readAs は各列のテキストがどのように読み取られたかを報告します。時刻のみの数値書式（h:mm、hh:mm:ss AM/PM）は HH:mm:ss として返されます。経過時間を表す [h]、[m]、[s] の書式は {"durationSeconds": number} を返し、秒単位で合計できます。

グループ化した分析

groupBy は、列名またはクローズド変換を受け取ります。カレンダー単位でグループ化する場合、明示的なタイムスタンプオフセットを適用した後、UTC が使われます。月と四半期のキーには年が含まれ、週には ISO 週年が使われ、曜日は月曜日が 1、日曜日が 7 となり、時間は 0 から 23 となります。単純な列は、columns で型を明示するか、同じ列について指標や条件ですでに型付きの読み取りが必要な場合を除き、保存されているキーをそのまま保持します。セルを読み取る場合は、元の値が返されます。

数値の bins は厳密な昇順の境界値で、アンダーフローとオーバーフローにそれぞれ別のグループを設けます。区間には下限が含まれ、上限は含まれません。固定の width には任意で origin（デフォルトはゼロ）を指定できます。正準的な十進演算により、0.3 は 0.1 の境界上に正確に配置され、直前の表現可能な値がそのバケットに移動することはありません。異なる有限数として表現できない境界値は拒否されます。キーが欠損している場合は null グループになり、派生キーを読み取れない場合は ungroupedRows にカウントされ、その例は warnings に含まれます。

pivotBy は、範囲が制限されたグループ化キーを出力列に変換し、キーと指標の組み合わせごとに 1 列を作成します。組み合わせが存在しない場合、カウントにはゼロ、数値指標には null が返されます。入力に該当する組み合わせがわずかしか含まれていない場合でも、密な結果を確保する前に、行キー数 × ピボットキー数 × 指標数の全体数を検査します。上限は指標セル 10,000 個です。

median、p50、p90、percentile は、正確な包含型線形補間（R7）を使用し、 Excel の PERCENTILE.INC と一致します。パーセンタイル引数は 0 以上 1 以下です。同一の指標選択で共有されるサンプルは一度だけ保持され、呼び出し全体で 100 万値の予算が適用されます。予算を超えるリクエストは拒否され、近似値に黙って変更されることはありません。各指標には独自の where を指定できます。これらの条件は、呼び出しの最上位フィルターの後に AND で結合されます。counted、skipped、filtered はそれぞれ、使用可能な値、読み取り不能または欠損している値、指標の条件によって除外された行を区別します。

groupingSets は、1 回のスキャンで主結果の横に独立した内訳を追加します。各セットには独自のグループ化キーと診断情報がありますが、列の読み取りとグローバルなリソース予算は共有されます。compact は、損失と曖昧さの診断情報を保持しながら、重複する来歴情報を削減します。test/aggregate-analysis.spec.ts の 2,000 行、15 列のコマース回帰テストでは、全体合計、国別、カテゴリ別、支払い別、36 か月分の内訳を、8 KiB 未満の 1 つの応答で検証します。

列の解釈をプロファイル化して再利用する

profile_sheetは、既定では先頭の長方形領域（データ行1,000行、列16列）をサンプリングします。上限は行5,000行、列64列、セル64,000個です。サンプリングした行と省略した行、および列を報告します。信頼度は、読み取り可能な種類のうち最も多い種類の値を、サンプリングした欠損値以外の値の数で割ったものです。未確認のデータについての確率ではありません。各プロファイルには、形式、欠損数、異なる値の数、最大値と最小値、頻出値、読み取り不能な値の例、識別子の兆候が含まれます。列ごとの異なる値の追跡は1,000個で停止します。その場合、件数は下限となり、報告される頻度は明示的に不完全なものとなります。種類が同数、または曖昧な場合は、混在として扱われます。

結果のcolumns配列とcolumnMode: "letter"は、他のグリッドツールにそのまま渡せます。推奨される数値列には必ずidentifiers: "refuse"が設定されるため、サンプリング範囲を超える先頭ゼロ付きの識別子や桁数の多い数字の識別子も除外され、件数に含まれます。呼び出し元が明示的に指定した数値列では、従来の既定値identifiers: "read"が維持されます。

read_sheetは元のvaluesを保持します。columnsを明示し、includeTyped: trueを指定すると、並行するグリッドtypedValuesが追加されます。欠損セルと読み取り不能なセルは、この追加グリッド内でのみnullになります。typed診断では両者を区別し、上限付きの例を含めます。指定されていない列は元の型を維持します。解釈、ロケール、リテラルのリストはカーソルに引き継がれ、競合するオプションは拒否されます。columnsを指定したfind_in_sheetは、指定列の正規化された値を検索し、元のvalueとtypedValueを返します。また、スキャンした入力済みセルのうち変換に失敗した件数を数えます。columnsを指定しない場合、検索では従来どおり元のテキストが使われます。

ロケール、欠損値、ブール値、時間の長さ

CSVのデコードでは、UTF-8／UTF-16、Windows-1251／1252／1254／1256、ISO-8859-9、Shift_JIS、GB18030、Big5、EUC-KRを明示的に指定できます。レガシーエンコーディングが自動的に推測されることはなく、不正なマルチバイトシーケンスは拒否されます。同じエンコーディングの選択は、ページング用カーソルにも引き継がれます。

デコード後の最初の物理行が正確にsep=Xまたは"sep=X"で構成されている場合、カンマ、セミコロン、タブ、パイプのいずれかが区切り文字として宣言されます。sepキーワードではASCIIの大文字・小文字を区別しません。空白、その他の区切り文字、それ以降の類似した記述は通常のデータとして扱われます。タブは実際のタブ文字である必要があり、2文字の表記\tは認識されません。認識された行は、ヘッダーの選択と、レコード数、行の不揃い、空白行、数式らしき行のカウントの前に取り除かれます。最初に残ったレコードがシートの行1になります。構文エラーでは引き続きファイルの物理行番号が報告され、csv.lineBreakには宣言行の行末も含まれます。区切り文字が明示されていない場合、csv.delimiterSourceは"sep"になります。明示的なdelimiterが優先され、ソースは"explicit"のままです。宣言と競合する場合は警告が追加されますが、宣言行は引き続き取り除かれます。BOMと厳密なデコードのチェックが先に実行されます。CSVプロファイルのレシピを参照してください。 明示的な数値列では、小数点や桁区切り記号の代わりに locale と numberingSystem を指定できます。たとえば、{"column":"Amount","type":"number","locale":"ar-EG","numberingSystem":"arab"} のように指定します。 小数点以下の数字体系、ローカルの区切り記号、符号、桁区切りのグループサイズは、インド式の3+2の桁区切りを含め、実行環境のIntlデータからコンパイルされます。対応していないロケールや数字体系は受け付けません。 日付列には、固定の format、明示的な order、または曖昧さのない日付を指定できます。明示的に指定したロケールは、書式形式と単独形式の両方を含むグレゴリオ暦の月名を提供しますが、日と月の順序は決定しません。スラッシュやハイフンを使った日付の順序は列の値から判断し、ピリオド区切りの日付はすべてのロケールで日を先に読み取ります。CLDRのロケールで、ピリオド区切りの数値日付を月から始めるものはないためです。ロケールはファイルの言語を示すものであり、読み手の言語を示すものではありません。ロケールの区切り記号で読み取った値が、列固有の記号で読み取った値と異なる場合は、警告でその値を示します。グレゴリオ暦以外のカレンダーの指定は受け付けません。ロケールを省略すると、既存の数値・日付推定の動作が決定論的に維持され、ホストのロケールが選択されることはありません。Unicodeの10進数字は正規化されますが、丸囲み数字、ローマ数字、その他の任意の互換文字が数値として扱われることはありません。

missingValues、trueValues、falseValues は設定可能なリストで、列ごとに上書きできます。欠損値の既定トークンは N/A、NULL、-、—、#N/A です。Nullと空文字列は常に欠損値です。missingValues: [] とすると、その他のトークンはリテラルテキストとして保持されます。Excelに保存されたエラーは引き続きエラーとして扱われます。真のトークンは true、yes、y、Evet、E、偽のトークンは false、no、n、Hayır、H です。呼び出し元が指定するリストでは、残り2つのリストの既定値から単語が補われます。列は、該当する値がそれ以外の値として読み取られる値より多い場合に限り、ブール値または期間として読み取られます。そのため、成績の E や単独の 100:30 によって列の残りの値が読み直されることはありません。テキスト比較では、テキストが欠損値トークンと一致するセルも検索対象になります。たとえば、eq "N/A" は N/A を検索します。 照合では大文字・小文字とアクセントの違いが無視され、設定したトークンはどの文字体系でも使用できます。重複するリストは受け付けません。数値の0と1がブール値として自動的に扱われることはありません。countTrue、countFalse、trueRatio は有効なブール値を対象とし、読み取り可能な値がない場合、比率はnullになります。

time 列では、8:15 のような時刻を 08:15:00 として読み取ります。duration 列では、25:30 や P1DT2H のような経過時間またはISO形式の固定長の日付・時刻期間を読み取り、{"durationSeconds":91800} または {"durationSeconds":93600} に変換します。暦年・暦月と閏秒は受け付けません。数値の期間メトリクスは秒を使用し、単位を報告します。期間として自動的に読み取るには、列に期間を示す手がかりが必要です。単なる時刻は期間の合計に含まれません。 パーセントやパーミルの値は単位メタデータ付きの小数として扱われます。通貨ラベルは保持されますが、為替レート換算は行われません。CSVプロファイルのレシピと、リポジトリのlabにある再現可能なジェネレーターおよびファズテストの手順を参照してください。

名前付きテーブルと保存された行の表示状態

read_sheet、profile_sheet、find_in_sheet、aggregate_sheet では、table: "Orders" を指定できます。 名前を指定すると、ワークブック全体から宣言済みのテーブルが選択されます。sheetName を指定すると検索対象が制限されます。 名前の照合では Unicode の大文字小文字を区別しない処理が行われ、曖昧な一致は拒否されます。選択される範囲はテーブルの データ本体であり、ヘッダー行と集計行は含まれません。ヘッダー行が非表示の場合も、列参照にはテーブルで宣言された名前が使われます。 テーブルを range または競合する headerRow と組み合わせることはできません。宣言済みのデータ行がないテーブルと、サポートされていないヘッダー行数または集計行数を持つテーブルは明示的に拒否されます。宣言済みのデータ本体に空白セルしか含まれていない場合も、読み取り可能です。

保存された非表示行を省くには、visibleOnly: true を指定します。手動で非表示にした行と、AutoFilter の適用後に作成者が非表示として保存した行が対象です。リーダーは保存されたフラグを使用し、 フィルター条件を再評価しません。このような回答にはすべて、basis: "savedHiddenRows"、hiddenRowsSkipped、filterCriteriaReevaluated: false を含む visibility が含まれます。また、宣言されている場合は、関連する AutoFilter の範囲も含まれます。 一致する非表示フラグなしで保存された条件は、行を除外しません。Excel では、保存された行の表示状態とフィルター定義は別々のデータです。

フィルターを適用した読み取りでは、values に加えて rowNumbers が返され、各行の元のワークシート上の位置が保持されます。 カーソルには table と visibleOnly の両方が紐付けられます。省略されたオプションは引き継がれ、競合する指定は拒否されます。 hiddenRowsSkipped は、読み取りでは処理したページ、検索と集計では選択範囲全体、プロファイルでは選択されたデータ行を対象とします。 プロファイルの合計値とサンプリング上限は、対象となる表示行を基準に数えられます。非表示行による除外は別途報告されます。CSV はテーブルのメタデータにも非表示行フラグにも対応していないため、CSV に対する table と visibleOnly: true は拒否されます。

ネイティブの数値形式とリッチセル値

ネイティブの数値セルは、適用される数値形式セクションの意味を保持します。経過時間を表す [h]、[m]、[s] トークンは、負の値や24時間を超える期間を含め、ブックの日付システムに関係なく秒数を返します。パーセンテージ形式は、保存済みの分数を再スケーリングせずに unit: "fraction" を追加します。たとえば、0.25 は 0.25 のままです。明示的な通貨トークンは集計メトリクスの記述子に引き継がれ、曖昧な通貨記号は記号ラベルを保持します。トークンを解釈する前に条件付きセクションが選択され、引用符で囲まれたリテラルやエスケープされたリテラルによって通常の数値が日付やパーセンテージとして解釈されることはありません。これは範囲を限定したセマンティックリーダーであり、完全な表示レンダラーではありません。サポートされていない形式構文では、ネイティブの数値が保持されます。ルールはMicrosoft の数値形式仕様に従います。

セル内画像は、#VALUE! の互換性キャッシュの代わりに、imageId と任意の altText および decorative フィールドを返します。get_images でも、anchor: "inCell"、ソースの cell、同じメディア ID とともに一覧表示されます。検証済みのリッチ画像リレーションシップは、他の内部パッケージパスを参照する場合があります。既存のメディア ID を維持しながら、ID はワークシートや呼び出し順序をまたいで安定します。描画画像では、保存済みの代替テキストも保持されるようになりました。 サポート対象のリンクデータ形式は _linkedentity2 です。閉じた linkedValue オブジェクトには、保存済みの displayText と、存在する場合はそのエンティティ ID、カルチャ、数値のサービス ID が含まれます。リンク先プロバイダーは更新されず、外部画像もダウンロードされません。また、入れ子のプロパティバッグは展開されません。検索では、表示上の制限を適用する前に、保存済みの代替テキスト全体またはリンクラベル全体との一致を調べます。不明なリッチタイプでは、保存済みスカラー値と、サポートされていないことを明示する richValue の注記が保持されます。不正な参照インデックスやリレーションシップチェーンは corrupt_workbook として拒否されます。

配列数式の注記では、アンカー、宣言された ref、dynamic フラグ、任意の collapsed フラグが保持されます。キャッシュ済みのスピルメンバーでは、それぞれの値が保持され、同じ配列アンカーが参照されます。リーダーは数式の再計算も、欠落したキャッシュの補完も行いません。ネイティブおよびメタデータに基づく #SPILL! エラーと #CALC! エラーには、妨げているセルや計算原因を推測することなく説明が付与されます。固定された元の XlsxWriter および Microsoft Open XML SDK のフィクスチャ、独立した XML 検証ツール、ライセンス、検証済みの対応範囲は、RICH_VALUE_SOURCES.md に記録されています。

aggregate_sheet.errorDistribution は、呼び出しレベルおよびメトリクスレベルのフィルタリング後に、対象となるネイティブエラーセルの個数を重複なく数えます。メトリクスの重複、グループ化セット、ピボットによって、物理セルのカウントが増えることはありません。最大32個のコードについて、それぞれ3つのサンプルアドレスが表示されます。上限を超えたコードや長すぎるコードは、明示的な other バケットに入ります。数値、ブール値、極端な値のメトリクスでは、skippedErrors は skipped の内数として報告されます。保存済みのエラーは、引き続き countValues と countDistinct にカウントされます。画像とサポート対象のリンク値はエラーとして分類されません。

メタデータの読み取り方法

すべてのツールは @sezzlee/ooxml-core を通じて OOXML パーツを直接読み取ります。対象には、セル、数値形式、数式、ハイパーリンク、結合セル、定義された名前のほか、データの入力規則、Excel テーブル、条件付き書式、画像、ウィンドウ枠の固定も含まれます。実行時にスプレッドシートライブラリは使用されません。SheetJS と exceljs は開発時の依存関係です。exceljs はテスト用フィクスチャの作成に使用され、セルリーダーは参照用の SheetJS と比較されます。

OOXML パーツは、@sezzlee/ooxml-core 独自の XML トークナイザーで名前空間を考慮して読み取られます。照合は (namespace uri, local name) に基づいて行われ、ファイルに記述されたプレフィックスは参照されません。そのため、<x:dataValidation> と <dataValidation> は呼び出し側から見ると区別されません。したがって、これらのツールは、プレフィックス付きの .NET 出力や sheet.xml という名前のワークシートパーツを含む、あらゆる OPC レイアウトで動作します。

ツール	ソース
get_data_validations	ワークシートのパート、dataValidations/dataValidation。範囲はセルごとに展開せず、sqref の値をそのまま取得します。列全体を対象とするルールも正確なものとして扱われるため、dataValidationRuleCountExact は常に true です
get_tables	ワークシートの tableParts → シートの rels → xl/tables/*.xml。filterButton は位置ではなく colId で照合されます
get_conditional_formats	ワークシートの conditionalFormatting/cfRule。containsText ファミリーは、タイプと演算子に解析されます。cfvo type="formula" のしきい値の式は formula フィールドに保持されます
get_images	セルの vm → ワークブックのシートメタデータ → リッチバリュー構造とリレーションシップ → セル内画像のメディア。描画画像は、ワークシートの drawing → シートの rels → xl/drawings/*.xml → a:blip r:embed → 描画の rels → xl/media/* をたどります。twoCell、oneCell、absolute のすべてのアンカーが報告されます。range を持つのは 2 セルアンカーのみです。1 セルアンカーは左上の cell とサイズをピクセル単位の整数で取得します。サイズがカバーするセルは列幅によって異なるためです。絶対アンカーはサイズのみを取得します。get_charts も同じ方法でグラフを配置します
get_charts	ワークシートまたはグラフシートの drawing → グラフ／chartEx フレーム → タイプ、タイトル、軸（最小値／最大値／対数／数値形式）、系列参照とキャッシュ済みポイント、近似曲線、pivotSource を含む xl/charts/*.xml。各要素は親要素の下で照合されるため、データラベルの c:tx が系列名として扱われることはありません。数値キャッシュは数値、テキストキャッシュはテキストとして返され、キャッシュの numberFormat も返されます。複数レベルのカテゴリでは、外側の levels が保持されます。最初のプロットで使用されない軸は secondary となります。c15:filtered*Series 内の系列は hidden として一覧表示されます。Markup Compatibility により、AlternateContent の分岐が 1 つ選択されます。chartEx は unsupported として報告されます
describe_workbookは各シートのkindをworksheetまたはchartsheetとして示し、chartCountを報告します。チャートシートに対するread_sheet、profile_sheet、aggregate_sheet、find_in_sheet、get_merged_rangesはchart_sheetとして拒否され、復旧方法としてget_chartsが示されます。sheetNameを指定しない呼び出しは、最初に表示されているワークシートを対象とし、チャートシートは対象にしません。ただし、get_chartsはどちらの種類でも最初に表示されているシートを対象にします。ピボットテーブルとスパークラインは引き続き読み取れません。kind: "chart"を指定したget_imagesは、引き続きunsupported_object_kindを返し、get_chartsを案内します。

ファイル破損の申告は3つのコードに分かれており、互いの代わりにはなりません。not_a_workbook（ZIPアーカイブではない、またはブックパーツやワークシートが含まれていないZIP）、encrypted_workbook（OLE2/CFBヘッダー。パスワード保護されているか、旧形式のバイナリ）、corrupt_workbook（CRC-32チェックに失敗するパーツ、セントラルディレクトリと一致しないローカルヘッダー、整形式のXMLではないパーツ、または有効なUTF-8ではないパーツなど、破損したアーカイブ）です。破損したワークシートは、そのシートを読み取る呼び出しでのみ拒否されるため、ブック内のほかのシートは引き続き読み取れます。CSVは、サーバー独自のRFC 4180トークナイザーでレコードに分割されます。引用符の外では、CRLF、LF、CRのそれぞれがレコードの終端になります。不正な引用符の使い方は、問題箇所と行番号を含むcorrupt_workbookとなり、修復されることはありません。internal_errorにはrecoveryがありません。次に実行すべき既知の呼び出しがなく、存在するかのように示すと、問題のないファイルを修復するようエージェントに誤った指示をしてしまうためです。

開発

pnpm turbo run build --filter=@sezzlee/excel-mcp
pnpm turbo run test --filter=@sezzlee/excel-mcp
pnpm turbo run check-types --filter=@sezzlee/excel-mcp

テストはTurbo経由で実行してください。pnpm --filter @sezzlee/excel-mcp testは使用しないでください。単独のフィルターではdependsOn: ["^build"]がスキップされます。また、このパッケージはexports.default → ./dist/index.jsを通じて@sezzlee/file-coreを解決するため、単独のフィルターでは古いdistを使ってテストする可能性があります。

ツールの引数、エラーコード、または制限を変更すると、apps/docsの生成済みリファレンスも変更されます。pnpm --filter @sezzlee/docs genを実行して結果をコミットしてください。そうしないと、pnpm turbo run validate --filter=@sezzlee/docsが失敗します。