excel-spreadsheet-xlsx-csv

mcp-spreadsheet

Awesome MCP Servers で紹介されています - ディレクトリ掲載ページ | ライブホストエンドポイント、無料枠あり、登録不要。

スプレッドシートを AI アシスタントに渡して、話しかけてみましょう。マシン上の任意の .xlsx、.xlsm、.xlsb、.xls、.ods、.csv、.tsv ファイルを指定して、内容の確認、フィルター処理、新しい列の計算、別の形式での保存を依頼できます。実際のファイルにありがちな扱いにくい部分にも対応します。ヘッダー行を推測し、CSV がカンマ、セミコロン、タブのどれで区切られているかを判別し、引用符で囲まれたカンマや改行をそのまま保持し、$1,250.00 形式のテキストから数値を読み取り、列ごとのデータ型と空欄数を報告します。元のファイルを編集することはありません。明示的に overwrite を選択しない限り、すべての書き込みは新しいパスに行われます。データがマシンの外に出ることはなく、API キーも不要です。

公式 MCP Registry に登録されています（io.github.theluckystrike/excel-spreadsheet-xlsx-csv）。

AI Product Index に掲載されています - mcp.zovo.one/s/spreadsheet にライブリモートエンドポイントがあり、無料枠、登録不要です。

元のファイルに手を加えることなく、チャットから実際のスプレッドシートを読み取り、クエリし、拡張できます。

60秒でインストール

Claude Desktop では spreadsheet.mcpb v0.22.9 を使用してください。公開済みのチェックサム とバージョン付きダウンロードカタログで、対象のリリースを確認できます。npm パッケージは公開されていません。

ソースからインストールする場合は、Node.js 22 以降を使用し、まず共有依存関係をビルドしてください。

git clone https://github.com/theluckystrike/mcp-servers.git
cd mcp-servers
npm ci
node scripts/bootstrap-timezone.mjs
npm run build -w packages/mcp-license -w servers/spreadsheet

このエントリーを Claude Desktop の mcpServers、または Cursor の .cursor/mcp.json にマージしてください。絶対パスは、チェックアウト先に置き換えてください。

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["/absolute/path/mcp-servers/servers/spreadsheet/dist/index.js"]
    }
  }
}

Claude Code の場合：

claude mcp add spreadsheet -- node /absolute/path/mcp-servers/servers/spreadsheet/dist/index.js

Pro モードで実行するには、同じ設定ブロックで MCP_LICENSE_KEY を設定するか、キーを指定して license_activate を一度呼び出してください。

スプレッドシートの更新

バージョン 0.22.9 では、ベンダーがパッチを適用した SheetJS 0.20.3 を使用しています。数値の日付セルは、ブックに実際に保存されている時刻に従うようになりました。古いバージョンで作成された一部の数値日付ファイルは、ホーチミンなど、過去のタイムゾーンオフセットを持つ地域で、表示が30秒異なる場合があります。推測によるオフセットがデータに追加されることはありません。読み取りによってソースファイルが書き換えられることもありません。

ツール

ツール	機能
sheet_info	シート名、サイズ、推定ヘッダー行、列ごとの型、サンプル値、空のセル数
sheet_read	行をテキストテーブル、JSON レコード、または CSV として読み取ります。limit／offset によるページ指定、または A1 range に対応します
sheet_query	where でフィルタリングし、group_by + aggregate（sum、count、avg、min、max）で集計し、select で列を選び、sort（集計のエイリアスにも対応）と limit を指定します
sheet_stats	列ごとの件数、空のセル数、個別の値の数、最小値、最大値、合計、平均、中央値（テキスト列は上位の値）
sheet_find	ブック内の任意の場所からテキストを検索します。セルのアドレスと行のプレビューを返します
sheet_write	オブジェクトまたは配列の行を、新規ファイル、追記、または明示的な上書きとして書き込みます
sheet_add_column	数式から計算列を追加し、新しいファイルに保存します。数値の結果は入力と同じ桁数に丸められます（入力が小数点以下2桁なら、結果も小数点以下2桁）。decimals で変更できます
sheet_convert	シートを csv、xlsx、または json に変換します
license_status	Free または Pro のプランと、アップグレード方法
license_activate	Pro キーを有効化します（オフラインで検証）

リソーステンプレート：sheet://<path> は、そのファイルの sheet_info の概要を返します。 リソース：sheet://recent は、このサーバーが起動してから開いたファイルを、最新のものから順に一覧表示します（メモリ内のみで、ディスクには何も書き込まれないため、再起動するとリストは空になります）。

プロンプト：explore_sheet は内容がわからないファイルを順に調べます。まず sheet_info を実行し、次に実際に見つかった列を使って具体的な sheet_query を実行します。

できること

指示	ツール
「sales.xlsx を開いて、何が含まれているか教えてください。」	sheet_info
「最初の50行を表示してください。」	sheet_read
「North 地域で最も多くのユニットを販売した担当者は誰ですか？合計付きで上位5名を表示してください。」	sheet_query（group_by + aggregate）
「Email 列に空のセルはいくつありますか？注文サイズの中央値はいくつですか？」	sheet_stats
「'refund' に言及している行をすべて検索してください。」	sheet_find
「これを Q3 Results という名前の新しいシートとして書き込んでください。」	sheet_write
「Units と Unit Price を掛けた Revenue 列を追加し、元のファイルと同じ場所に CSV として保存してください。」	sheet_add_column
「この xlsx を JSON に変換してください。」	sheet_convert
「Free と Pro のどちらのプランを使っていますか？」	license_status
「ライセンスキーはこちらです。有効化してください。」	license_activate

使用例

docs/USER_VALUE_R2.md の400行のテストデータです。タイトル行と、実際のヘッダー（3行目）の上に空行があります。シートは Sales／Reps／Notes で、価格は "1,516.16" のような文字列として保存されています。1回の呼び出しで、生成スクリプトと照合して正解を確認しました：Turing 650、Hopper 567、Linus T 551、Lovelace 486、Liskov 290。

You: Which rep sold the most units in the North region? Top 5 with totals.

  sheet_query {
    path: "/Users/you/sales.xlsx", sheet: "Sales",
    where: "[Region] = \"North\"",
    group_by: ["Rep"],
    aggregate: [{ col: "Units", fn: "sum", as: "total_units" }],
    sort: { col: "total_units", dir: "desc" },
    limit: 5
  }

Assistant: Query: where [Region] = "North"; group by Rep; sum Units as total_units;
sort total_units desc; limit 5
5 groups from 102 of 400 rows, showing 5

Alan Turing     650
Grace Hopper    567
Linus T         551
Ada Lovelace    486
Barbara Liskov  290

応答には、実行したクエリ（Query: 行）が数値の前にそのまま表示されるようになりました。たとえば、依頼していないフィルターや、誤って追加された AND [Status] = "Closed" によって回答の範囲が狭まっていた場合、気づかないまま結果が絞り込まれるのではなく、そのことが見えるようになります。

2つ目の例は、元のファイルに手を加えずに列を追加して保存する方法です。

You: Add a Revenue column and save it as a CSV next to the original.

  sheet_add_column {
    path: "/Users/you/sales.xlsx", sheet: "Sales",
    name: "Revenue", formula: "[Units] * [Unit Price]",
    out_path: "/Users/you/sales.csv"
  }

Assistant: Wrote 400 rows (401 lines with header) to sales.csv.
Revenue = Units * Unit Price on every row, total 10,142,542.04.
Source file untouched.

where 言語と formula 言語

小さな式言語を直接解析して評価します。eval やコード実行はありません。裸の単語は常に列名として扱われ、JavaScript の値として扱われることはありません。

• 列：名前にスペースが含まれる場合は [Unit Price]、それ以外は Qty。大文字と小文字を区別せずに検索します。
• 比較：= != > >= < <= contains startswith endswith
• 論理：AND OR NOT と括弧。AND は OR より優先されます。
• 数式での算術演算：通常の優先順位で + - * % / を使います。
• 文字列：シングルクォートまたはダブルクォートで囲みます。引用符をエスケープするには、引用符を重ねます。

[Qty] >= 5 AND ([Status] = "open" OR [Region] contains "north")
[Amount] > 1000 AND NOT [Customer] startswith 'Test'

sheet_add_column の数式例：[Qty] * [Unit Price]。数式が参照するすべての列の値が小数点以下2桁以内の場合、結果は小数点以下2桁に丸められます。そのため、金額に対する [Amount] * 1.23 の結果は 40.7868 ではなく 40.79 になります。精度を自分で指定するには、decimals（0～10）を渡します。

CSV 内でテキストとして記述された数値は、桁数ではなくパターンに基づいて変換されます。1250.00、12.00、1,250.00 はすべて xlsx 出力で数値になるため、Excel の SUM で集計できます。識別子の形式をした値や曖昧な値はテキストのままです。007 は先頭のゼロを保持し、1.250,00 は推測による変換をせず、そのままにします。

テキストの比較では、大文字と小文字、および前後の空白を無視します。$1,250.00、1 250、12% などの値は数値として比較されるため、スプレッドシートでテキストとして保存されている列にも [Amount] > 1000 を適用できます。

Free と Pro

	Free	Pro
ファイルを読み取るすべてのツール（sheet_info、sheet_read、sheet_query、sheet_stats、sheet_find、sheet_add_column、sheet_convert）	最大 5 MB、5,000 行のファイル	制限なし（ファイル上限の 50 MB まで）
sheet_write、sheet_add_column、sheet_convert	ファイルごとに最大 500 行を書き込みます。これを超える場合は何も書き込まず、ツールがその旨を伝えます	制限なし
シート、形式、式言語	すべて	すべて

Free の読み取り上限を超えても、ツールは処理を行い、返せる範囲（先頭の 5,000 行）を返して、省略した内容を注記します。Free の書き込み上限を超える場合は、何も書き込みません。不完全なのに完成しているように見えるファイルを作るより、ファイルを作らない方がよいため、ツールは書き込みを拒否し、行数と上限を伝えたうえで、無料でできる回避策（先に行を絞り込む、または 500 行ずつ書き込む）を提案します。何も通知せずに失敗することはありません。

Pro の購入

このサーバーは $19、すべてのサーバーは $39 の買い切りで、永久に利用できます：https://mcp.zovo.one/buy/spreadsheet

データの保存方法

このサーバーは独自のデータベースを持たず、指定されたスプレッドシートファイルをディスク上で直接読み書きするだけで、それ以外のことは行いません。すべての書き込み（sheet_write、sheet_add_column、overwrite モードの sheet_convert）は、まず同じディレクトリ内の一時ファイルに書き込んでから、所定の場所に名前を変更します。そのため、書き込みが中断されても、元のファイルがそのまま残るか、新しいファイルが完全な状態で残るかのどちらかとなり、ファイルが途中で切り詰められることはありません。共有状態ファイルがないため、アドバイザリロックを取得する必要もありません。異なる出力先に書き込む2つの呼び出しが競合することはなく、同じファイルに対する overwrite の呼び出しを2回続けて行った場合は、単に順番に2回書き込みます。データをバックアップするには、スプレッドシートファイル自体をバックアップしてください。それ以外にコピーするものはありません。

制限事項と正直な注意点

• 無料プランの読み取り上限は 5,000 行、5 MB です。無料プランの書き込み上限はファイルあたり 500 行で、切り捨てずに拒否します。行数と上限を示すエラーが返されるため、完全に見える短いファイルが作成されることはありません。
• プランにかかわらず、ハード上限は 50 MB です。これを超えるファイルは、メモリ不足のリスクを避けるため、明確なメッセージとともに即座に拒否されます。
• where／formula の言語は意図的に機能を絞っています。正規表現、カスタム関数、1 つの数式内でのシート間参照には対応していません。比較、ブール論理、算術演算のみを扱います。
• xlsx への書き込みでは、ワークブックではなく 1 つのシートが置き換えられます。 append または overwrite を指定した sheet_write は、ワークブック全体を読み込み、指定したシートを差し替えて、ほかのシートをすべて書き戻すため、Sheet1 への追記後も Sheet2 とそのデータは保持されます。保持されないのは、書き込み対象のシートです。このシートは値から再構築されるため、そのシート上の数式、セルの書式、条件付き書式、グラフ、データの入力規則、結合セルは通常の値になります。ほかのシートは読み取ったとおりに保持されます。再現できない書式が対象シートにある場合は、事前にコピーを作成してください。
• テキストとして書き込まれた数値は、ロケールを考慮したルールで読み取られます。 1,250.00、1 250.00、$1,250.00、12,99、1.234,56、EUR 1 250,00 はすべて数値として読み取られます。小数点のカンマが受け入れられるのは、曖昧さのない形式（末尾にちょうど 2 桁があり、桁区切りにはピリオドまたはスペースを使う）に限られます。区切り文字が別の形式で混在する値（1,2500.00 など）は、推測されずテキストのままになります。先頭にゼロがある値（007）や、正確な演算ができる範囲を超える整数（9,007,199,254,740,991 を超える値）は、暗黙に変更されないようテキストのままになります。
• 日付はセルの型を維持します。 xlsx から読み取った日付セルは、クエリ中も xlsx への変換後も日付のままです。テキスト、CSV、JSON の出力では ISO 形式で表されます。日付は 2026-09-04、時刻を含むセルは 2026-09-03T15:30:00 となります。
• sheet_info のヘッダー行の推定はヒューリスティックです（上の行より空欄が少なく、テキスト密度が高い最初の行を探します）。タイトル行やヘッダーの上に空白行がある場合には対応していますが、あらゆるレイアウトに対応できるわけではありません。クエリを実行する前に、推定結果を確認できます。

トラブルシューティング

• npx がハングする、またはパッケージが見つからない：このパッケージの npm への公開は保留中です。公開されるまでは、.mcpb バンドルまたは上記のクローンしてビルドする方法を使用してください。
• .mcpb バンドルを使用する場合：Claude Desktop に直接インストールされるため、別途設定する必要はありません。
• クローンする方法を使用する場合：npm run build の実行後、サーバーバイナリは servers/spreadsheet/dist/index.js にあります。クライアントの command に node を指定し、その絶対パスだけを引数として指定してください。
• Node のバージョン：Node >= 18 が必要です。node -v で確認してください。
• 「Path does not exist」：メッセージには解決後の絶対パス（~ を展開したもの）が含まれます。実際のファイルの場所と照合してください。特に、サンドボックス化されたクライアントやコンテナー化されたクライアントでは注意が必要です。
• 行数のメッセージが表示され、書き込みが拒否される：無料プランの 500 行の書き込み上限に達しています。まず sheet_query でデータを絞り込むか、複数回に分けて書き込むか、Pro を有効にしてください。
• 何も表示されない／エラーが表面化しない：ログは stderr にのみ出力され、stdout には出力されません。Claude Desktop では Settings -> Developer -> サーバーのログファイルを確認してください。Claude Code ではターミナルまたは --mcp-debug を確認してください。

安全性

• 存在しないパスは、解決済みパスをメッセージに表示して拒否されます。~ は展開されます。
• 50 MB を超えるファイルは、メモリを使い果たすことなく、明確なメッセージとともに拒否されます。
• sheet_add_column と sheet_convert は新しいファイルに書き込みます。out_path を自分で指定しない限り、既存のファイルへの上書きは拒否されます。
• mode: "new_file" を指定した sheet_write は、既存のファイルへの書き込みを拒否します。ファイルの内容を置き換えるのは mode: "overwrite" だけです。
• 出力ファイルは一時的な名前で書き込まれてから所定の場所に名前を変更されるため、書き込みが中断されてもファイルが切り詰められることはありません。

プライバシー

すべてのデータはローカルにとどまります。ファイルの読み書きはお使いのディスク上で行われ、ライセンスキーは組み込みの公開鍵を使ってオフラインで検証されます。サーバーはネットワークリクエストを一切行いません。

CSV エクスポートの繰り返しチェック

CSV エクスポートを繰り返すワークフローについては、ローカル CSV ルールチェックガイドで、保存済みのポリシーを使って追加、削除、価格の最大絶対上昇額をチェックする方法を説明しています。ルールがファイルに適合するかどうかを判断する前に、無料のブラウザーデモをお試しください。CSV データはデモのブラウザー内にとどまり、この MCP サーバーから転送されることはありません。

このガイドで紹介しているのは、別途提案されている、買い切り価格 7 USD のオフライン Node CLI パックです。現在、購入手続きや予約注文はできず、この MCP サーバーの Pro ライセンスにも含まれていません。無料デモでは同じルールロジックを実行できます。提案されている有料特典は、再利用可能なローカルバンドルと CLI ワークフローです。受け付けるのは、順序が同一のヘッダーと一意のキーを 1 つだけ持つ UTF-8 CSV で、ファイルあたり最大 1 MB、5,000 行です。ストアへのインポートは行わず、インポートの安全性を保証するものでもありません。

任意の非同期ワークフローフィードバックは、サポート対象の CSV チェックを繰り返し行うケース、1 回限りの用途、または先にマッピングが必要な入力の特定に役立ちます。共有するのは一般的なワークフロー情報のみとしてください。CSV ファイルや連絡先情報を共有する必要はなく、通話や支払いも不要です。

組み合わせて使う

• mcp-time-tracker：export_csv で CSV をエクスポートし、ここでクエリを実行してデータを整形します。
• mcp-invoice：スプレッドシートから明細項目を取り出して、請求書に変換します。
• mcp-price-tracker：エクスポートした価格履歴をシートとして分析します。
• office-suite：1 回のインストールと 1 つの設定項目で、関連サーバーをすべて利用できます。
• ガイド：Cursor または Claude から Excel ファイルや CSV ファイルについて質問する

FAQ

はい。sheet_info はヘッダー行を推測して、選択した行を報告します。そのため、実際のヘッダーの上にタイトル行と空白行があるエクスポートも、何も指定せずに正しく開けます。

グループ化できます。sheet_query では、sum、count、avg、min、max を使う aggregate と group_by を指定でき、集計エイリアスで並べ替えることもできます。そのため、カテゴリ別の上位 N 件を尋ねる処理は 1 回の呼び出しで済みます。

いいえ。出力パスとしてソースを指すパスを明示的に指定しない限り、上書きされることはありません。sheet_add_column と sheet_convert は、デフォルトでは元のファイルと同じ場所に新しいファイルを書き込みます。

読み取りでは最初の 5,000 行が返され、省略された内容を示すメッセージが表示されます。500 行を超える書き込みは、切り詰められたファイルを生成するのではなく拒否されます。また、メッセージには行数、上限、無料で上限を回避する方法が表示されます。

いいえ。サーバーはお使いのマシン上でローカルに実行され、ファイルを直接読み取ります。ネットワークリクエストは一切行わず、書き込みを指示されたファイル以外のデータを保存することもありません。

theluckystrike によって作成されました。サポート：[email protected]

このドキュメントを MCP サーバーとして使う

Claude、Cursor、Windsurf、VS Code などの MCP クライアントは、インストールせずに GitMCP 経由でこのリポジトリのドキュメントを直接読み取れます。

• ドキュメント MCP URL：https://gitmcp.io/theluckystrike/mcp-spreadsheet