xlsx-tools-mcp

xlsx-tools-mcp

既存のファイル構造、スタイル、数式を維持しながら、Excel（.xlsx）ファイルを高精度で読み書きするための MCP サーバーです。

---

概要

xlsx-tools-mcp は、LLM エージェントに Excel の .xlsx ファイルへの、構造を維持した正確な読み取りおよび書き込みアクセスを提供する 29 個の Model Context Protocol（MCP）ツールを公開します。標準的な stdio MCP サーバーとして動作します。インストールして MCP クライアント（Claude Code、OpenCode など）に登録すると、クライアントのエージェントがシートの一覧表示、セル範囲の読み取り、値の検索、データの集計、セルや数式の書き込み、シート・行・列の管理、スタイルの適用、数式の再計算の強制を行えます。

既存のブックを編集する際、変更対象以外を破壊しないことを基本理念としています。

特徴

• openpyxl による構造を維持した書き込み — 既存のワークブックを読み込んで保存し直すため、編集対象に触れない限り、スタイル、結合セル、コメントなど、あらゆる要素が保持されます。
• LibreOffice による再計算で数式の結果を常に最新に維持 — openpyxl は数式の 文字列 を書き込みますが、評価は行いません。値または数式を書き込むたびに、サーバーはヘッドレスの LibreOffice を実行して実際の結果を再計算し、その後 errors_found を返します。これは、再計算によって発生した Excel のエラー値（#REF!、#DIV/0!、#N/A、…）を示します。
• python-calamine による高速な読み取り — Rust ベースのパーサーにより、正確かつ高速な型推論を実現します。数式、スタイル、コメントが必要な場合や、calamine でファイルを解析できない場合は、openpyxl に自動でフォールバックします。
• pandas ベースのグループ化・集計とクエリ — aggregate_sheet と query_sheet は、元の構造を損なわずに処理を実行します。また、コードインジェクションを防ぐ AST 式検証を備えています。
• Excel のネイティブオブジェクト — オートフィルターとスタイルを備えた正式な Excel テーブル（create_table）や、ネイティブのグラフ（棒、折れ線、円、散布図の create_chart）を作成できます。
• シートのライフサイクルと書式設定 — シート名の変更（rename_sheet）、スタイルを保持したシートの複製（copy_sheet）、範囲のクリア（clear_range）、列幅の自動調整（autofit_columns）ができます。
• クロスプラットフォームでの高い信頼性（Windows、macOS、Linux） — 大文字と小文字を区別しないパス制限、カンマまたはセミコロン ; 区切りの環境変数、ロック発生時に一時的な再試行を行う安全なアトミックファイル置換（WinError 32／ウイルス対策ソフトへの対策）、ウィンドウのちらつきを抑えたサイレントなヘッドレス再計算を備えています。
• ファイル単位のロック — 同じワークブックにアクセスするツール呼び出し（または他のプロセス）は、同階層の <path>.lock ファイル（filelock）を介して直列化されるため、書き込みが交錯してファイルが破損することはありません。
• パス制限 — XLSX_MCP_ALLOWED_DIRS（カンマまたはセミコロン区切り）を指定すると、すべての読み取りと書き込みを特定のディレクトリ内に制限できます。設定されている場合、境界外のファイルにアクセスしようとすると AccessDeniedError が発生します。大文字と小文字を区別しないパス比較や、Windows の複数ドライブのパスに対応しています。
• 自動バックアップと復元 — 書き込みツールは、backup=True の場合（既定値は XLSX_MCP_AUTO_BACKUP=true）、ワークブックを変更する前に同階層の .bak ファイルを自動的に作成します。restore_backup を使うと、変更をアトミックに元に戻せます。
• 数式インジェクション対策 — write_cells と append_rows は、データ流出や悪意のあるリンクを防ぐため、既定で WEBSERVICE、HYPERLINK、INDIRECT、RTD、CALL、REGISTER、または DDE コマンド（|）を含む数式を拒否します。このチェックを回避するには、allow_external_formulas=True を渡します。
• XML 爆弾対策 — defusedxml パッケージが自動的に依存関係に追加されます。openpyxl はこれを検出して強化された XML パーサーを使用するため、悪意のある xlsx の XML によるリソース枯渇を防げます。
• 起動時のファイル読み込み — XLSX_MCP_FILES にワークブックを 1 つ以上指定すると（カンマまたはセミコロン区切り）、起動時に読み込まれます。これにより、ツールの呼び出し時に path を省略したり、完全なファイルシステムパスの代わりに短いエイリアスを使用したりできます。

---

ダウンロード統計

pypistats.org によるリアルタイムの統計で、ミラー経由のダウンロードは含まれません。これはダウンロードイベントの数であり、ユニークユーザー数やインストール数ではありません。1 人のユーザーが多数のダウンロードを発生させることがあります（CI、再インストール、Docker イメージの再ビルド、ミラーなど）。

---

アーキテクチャ

┌──────────────────────── Supervisor (MCP transport, stdio)
│  src/xlsx_tools_mcp/server.py     29 MCP tools + instructions
│  src/xlsx_tools_mcp/settings.py   env vars, preloaded files, path resolution
│  src/xlsx_tools_mcp/locking.py    per-file <path>.lock serialization
│  src/xlsx_tools_mcp/errors.py     domain error types
│  src/xlsx_tools_mcp/recalc.py     LibreOffice headless recalc + error scanning
│
├─ Read path
│  src/xlsx_tools_mcp/io/reader.py      calamine primary → openpyxl fallback
│  src/xlsx_tools_mcp/io/transform.py   pandas aggregation on read results
│
└─ Write path
   src/xlsx_tools_mcp/io/writer.py      openpyxl → LibreOffice recalc → scan errors

io レイヤー（io/）は、MCP トランスポート（server.py）から意図的に分離されています。各 MCP ツールは、対象のパスを解決し、ファイル単位のロックを取得して、io レイヤーの関数を呼び出す薄いラッパーです。これにより、中核のロジックを MCP から独立させ、直接テストできるようにしています（tests/ を参照）。

再計算のトレードオフ

セルの値または数式に影響する書き込みの後、サーバーはファイルに対して soffice --headless --convert-to xlsx を実行し、すべての数式に実際の計算結果を反映します。この往復処理によって数式は再計算されますが、ワークブック全体を再エクスポートします。これはトレードオフであり、完全なビット単位の保持を保証するものではありません。openpyxl なら保持できる機能でも、同じ状態で維持されない場合があります。たとえば、ピボットテーブル、グラフ、データ検証、一部の書式、定義された名前などです。

こうしたリスクが問題となる、構造が複雑なワークブックを扱う場合は、値や数式を書き込むツール（write_cells、append_rows、insert_rows、delete_rows、insert_columns、delete_columns）で recalculate=False を指定すると、openpyxl のみで保存し、往復処理を完全に省略できます。

---

要件

• Python ≥ 3.10
• LibreOffice — 任意ですが、推奨します。数式の再計算にのみ必要です。インストールされていなくても書き込みは成功します（openpyxl 経由で保存されます）が、数式は再計算されず、message フィールドに警告が返されます。

LibreOffice のインストール：

# macOS
brew install --cask libreoffice

# Debian / Ubuntu
sudo apt-get install -y libreoffice-calc

# Windows
winget install TheDocumentFoundation.LibreOffice

サーバーは PATH 上の soffice / libreoffice、macOS の標準インストール先（/Applications/LibreOffice.app/Contents/MacOS/soffice）、および Windows の標準パス（%ProgramFiles%\LibreOffice\program\soffice.exe など）を確認して、LibreOffice を検索します。Windows では、ヘッドレス再計算は画面のちらつきなしで（CREATE_NO_WINDOW）、分離されたユーザープロファイルを使用して、バックグラウンドで実行されます。

---

インストール

このサーバーは stdio トランスポート（標準の MCP）を使用します。インストール後、MCP クライアントが接続してツールを呼び出すまで待機します。通常、自分でサーバーを実行する必要はありません。クライアントに登録してください。

1. PyPI から uvx 経由でインストール（推奨 — クローン不要）

uvx xlsx-tools-mcp

uvx は、プロジェクトに影響を与えることなく公開済みパッケージを取得して実行します。MCP クライアントを手早く動作させる最も簡単な方法です（以下の設定例を参照）。

2. ソースからインストール

git clone https://github.com/ruriazz/xlsx-tools-mcp.git
cd xlsx-tools-mcp
uv sync
# run the server (useful for local dev / debugging):
uv run xlsx-tools-mcp

3. pip 経由でインストール

pip install xlsx-tools-mcp

これによりコンソールエントリーポイントがインストールされ、サーバーを直接実行できます。

xlsx-tools-mcp

---

MCP クライアントの設定

どのクライアントでも、最も簡単な登録方法は uvx xlsx-tools-mcp を使うことです（クローン不要で、常に公開済みバージョンを使用します）。

Windows 向けのヒント： JSON クライアント設定ファイル（.mcp.json、opencode.json）では、JSON のエスケープシーケンスによるエラーを防ぐため、スラッシュ（例："C:/path/to/data.xlsx"）またはエスケープしたバックスラッシュ（例："C:\\\\path\\\\to\\\\data.xlsx"）を使用してください。

Claude Code

claude mcp add xlsx-tools-mcp -- uvx xlsx-tools-mcp

または、プロジェクト内の .mcp.json 経由で設定します。

{
  "mcpServers": {
    "xlsx-tools-mcp": { "command": "uvx", "args": ["xlsx-tools-mcp"] }
  }
}

OpenCode

プロジェクトの opencode.json またはグローバル設定の ~/.config/opencode/opencode.json に記述します。

{
  "mcp": {
    "xlsx-tools-mcp": { "type": "local", "command": ["uvx", "xlsx-tools-mcp"], "enabled": true }
  }
}

ソースのクローンから実行する場合

PyPI からインストールせずにリポジトリをクローンした場合は、uvx xlsx-tools-mcp を動的な uv run 形式に置き換えて、クライアントからローカルのチェックアウト先を指定してください（クローン先の絶対パスを使用します）。

Claude Code .mcp.json：

{
  "mcpServers": {
    "xlsx-tools-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/xlsx-reader", "run", "xlsx-tools-mcp"]
    }
  }
}

OpenCode：

{
  "mcp": {
    "xlsx-tools-mcp": {
      "type": "local",
      "command": ["uv", "--directory", "/absolute/path/to/xlsx-reader", "run", "xlsx-tools-mcp"],
      "enabled": true
    }
  }
}

/absolute/path/to/xlsx-reader を、実際のクローン先の場所に置き換えてください。

---

ファイルの事前読み込み（XLSX_MCP_FILES）

起動時にワークブックを事前読み込みするには、XLSX_MCP_FILES 環境変数を MCP サーバー設定の env セクションに設定してください（対話型シェルではありません。サーバーはクライアントによって起動されます）。形式は、カンマまたはセミコロンで区切った alias=absolute/path エントリー、または絶対パスのみです。

XLSX_MCP_FILES=name=/abs/path/to/name.xlsx,report=/data/report.xlsx

パスのみを指定した場合、ファイル名が既定のエイリアスになります。

XLSX_MCP_FILES=/abs/path/to/sales.xlsx

エイリアスには alias または filename を使用します。

• ファイルを1つ設定した場合 → すべてのツールで path を省略して呼び出せます。
• 複数のファイルを設定した場合 → path にエイリアス（またはファイル名）を指定します。
• list_configured_files() は、エイリアスと絶対パスの対応を返します。
• 事前読み込みしていないファイルも、絶対パスと相対パスをそのまま使用できます。

Claude Code — 事前読み込みを設定した .mcp.json：

{
  "mcpServers": {
    "xlsx-tools-mcp": {
      "command": "uvx",
      "args": ["xlsx-tools-mcp"],
      "env": {
        "XLSX_MCP_FILES": "report=/data/report.xlsx,sales=/data/sales.xlsx"
      }
    }
  }
}

事前読み込みを設定した OpenCode：

{
  "mcp": {
    "xlsx-tools-mcp": {
      "type": "local",
      "command": ["uvx", "xlsx-tools-mcp"],
      "env": { "XLSX_MCP_FILES": "report=/data/report.xlsx,sales=/data/sales.xlsx" },
      "enabled": true
    }
  }
}

---

ツールリファレンス

全29個のツールです。特に記載がない限り、path にはファイルシステムのパス、事前に読み込まれたエイリアス／ファイル名を指定できます。また、ファイルが1つだけ事前に読み込まれている場合は省略できます。例外は create_workbook です。新しいファイルが事前に読み込まれることはないため、path は必須です。

レスポンスの形式（すべての書き込みツール）： 書き込みツールはすべて {"saved": bool, "recalculated": bool, "errors_found": list, "message": str} を返します。errors_found が空でない場合は、{"sheet": "...", "cell": "B2", "error": "#DIV/0!"} のリストです。

検査／読み取り

ツール	説明
list_configured_files()	XLSX_MCP_FILES を通じて起動時に事前読み込みされたファイルを、エイリアス → 絶対パスのマップとして一覧表示します。利用可能なファイルが不明な場合は、最初にこれを呼び出してください。
list_sheets(path?)	ワークブック内のすべてのシートを、概算の行数／列数（calamine）とともに一覧表示します。
get_workbook_info(path?)	ワークブックレベルのメタデータを返します。シートごとの正確なサイズ、max_row／max_column、シートの状態、アクティブなシート、定義済みの名前が含まれます。
read_sheet(sheet, cell_range?, max_rows?, offset_row?, format?, path?)	セルの値を読み取ります。cell_range で読み取り範囲を指定できます。max_rows で行数の上限を設定できます。offset_row でページネーション用に行をスキップできます。format は "array"（2次元リスト）、"records"（先頭行をキーとして使う辞書のリスト）、または "markdown"（テーブル文字列）を指定できます。
get_cell(sheet, cell, path?)	1つのセルの詳細情報を返します。値（キャッシュされた計算結果）、数式、表示形式、フォント（太字／斜体／サイズ／色）、塗りつぶし色、結合状態、コメントが含まれます。
search_workbook(query, sheet?, match_case?, limit?, path?)	1つまたはすべてのシートを対象に部分文字列検索を行います。sheet で対象シートを限定できます。match_case=True で大文字と小文字を区別し、limit で一致件数の上限を設定できます。{"sheet", "cell", "value"} を返します。
aggregate_sheet(sheet, group_by, agg, cell_range?, has_header?, path?)	pandas を使用してグループ化と集計を行います。group_by は列名のリスト（ヘッダー行から取得）です。agg は列名 → 集計関数の対応を指定します。例：{"amount": "sum"}。has_header=True（デフォルト）では、先頭行から列名を読み取ります。{columns, records, row_count} を返します。
profile_sheet(sheet, sample_rows?, path?)	シートのメタデータをプロファイルします。推定された型、null の件数、最小値／最大値、サンプル値が含まれます。
query_sheet(sheet, filter_query, columns?, max_rows?, cell_range?, path?)	AST による強化されたコードインジェクション対策を備えた pandas 式を使用して、シートのデータをフィルタリングします。

書き込み

ツール	説明
create_workbook(path, sheets?, overwrite?)	新しい .xlsx／.xlsm ワークブックを作成します。sheets のデフォルト値は ["Sheet1"] です。overwrite=True を指定すると、既存のファイルを置き換えます。path は必須です（新しいファイルが事前に読み込まれることはありません）。
write_cells(sheet, cells, create_sheet_if_missing?, recalculate?, allow_external_formulas?, backup?, path?)	指定したセルに値や数式を書き込みます。cells は {"cell": "A1", "value": ...} または {"cell": "B1", "formula": "=A1*2"} のリストです。必要に応じて先にシートを作成できます。recalculate=True（デフォルト）を指定すると、LibreOffice による再計算が実行されます。
append_rows(sheet, rows, create_sheet_if_missing?, recalculate?, allow_external_formulas?, backup?, path?)	最後に使用されている行の後に行を追加します。rows は、各行が列順のセル値のリストであるリストです。
create_sheet(sheet, index?, path?)	空のシートを追加します。index は 0 始まりの挿入位置です。省略すると末尾に追加されます。
delete_sheet(sheet, path?)	シートを削除します。シートが 1 つしか残っていない場合は失敗します。
rename_sheet(old_name, new_name, path?)	既存のシートの名前を変更します。
copy_sheet(source_sheet, target_sheet, path?)	内容、数式、スタイルを含めてシートを複製します。
insert_rows(sheet, start_row, count?, recalculate?, path?)	start_row（1 始まり）の前に空の行を挿入し、既存の行を下に移動します。count のデフォルト値は 1 です。
delete_rows(sheet, start_row, count?, recalculate?, path?)	start_row（1 始まり）から行を削除し、それより下の行を上に移動します。count のデフォルト値は 1 です。
insert_columns(sheet, start_column, count?, recalculate?, path?)	start_column（1 始まり）の前に空の列を挿入し、既存の列を右に移動します。count のデフォルト値は 1 です。
delete_columns(sheet, start_column, count?, recalculate?, path?)	start_column（1 始まり）から列を削除し、右側の列を左に移動します。count のデフォルト値は 1 です。
merge_cells(sheet, cell_range, path?)	矩形範囲（例："A1:C1"）を 1 つのセルに結合します。
unmerge_cells(sheet, cell_range, path?)	以前に結合した範囲の結合を解除します。
set_cell_style(sheet, cell_range, style, path?)	範囲（例："A1:D1"）に書式を適用します。style のキー：bold、italic、font_size、font_color（16 進 RGB、例："FF0000"）、bg_color（16 進 RGB）、horizontal、vertical（配置）、border（"thin"、"medium"、"thick"、…）、number_format（例："#,##0.00"）。
autofit_columns(sheet, min_width?, max_width?, padding?, path?)	テキストの最大長に基づいて列幅を自動調整し、表示の切り詰めを防ぎます。
clear_range(sheet, cell_range, clear_values?, clear_styles?, path?)	行や列を削除せずに、指定した範囲のセル値やスタイルを消去します。
create_table(sheet, cell_range, table_name, style_name?, show_filter?, show_row_stripes?, path?)	範囲に正式な Excel テーブルを作成します。
create_chart(sheet, chart_type, data_range, categories_range?, title?, target_cell?, path?)	ネイティブの Excel グラフ（棒グラフ、折れ線グラフ、円グラフ、散布図）を追加します。
recalculate_workbook(path?)	LibreOffice のヘッドレス再計算を強制的に実行し、見つかった数式エラーを報告します。
restore_backup(backup_path, target_path)	.bak バックアップファイルを対象のワークブックにアトミックに復元します。

ペイロードの例 — write_cells

数式と値を書き込む呼び出し：

{
  "sheet": "Sheet1",
  "cells": [
    { "cell": "A1", "value": 100 },
    { "cell": "B1", "formula": "=A1*2" }
  ],
  "recalculate": true,
  "path": "/data/budget.xlsx"
}

対応するレスポンス：

{
  "saved": true,
  "recalculated": true,
  "errors_found": [],
  "message": "Recalculated with LibreOffice headless."
}

この操作の対象となった数式でエラーが発生した場合、errors_found は次のようになります。

{
  "saved": true,
  "recalculated": true,
  "errors_found": [
    { "sheet": "Sheet1", "cell": "C5", "error": "#DIV/0!" }
  ],
  "message": "Recalculated with LibreOffice headless."
}

ペイロードの例 — query_sheet

{
  "sheet": "Sales",
  "filter_query": "Revenue > 500 and Status == 'PAID'",
  "columns": ["Customer", "Revenue"],
  "max_rows": 10
}

ペイロードの例 — create_table と create_chart

{
  "sheet": "Summary",
  "cell_range": "A1:D10",
  "table_name": "SalesTable",
  "style_name": "TableStyleMedium9"
}

{
  "sheet": "Summary",
  "chart_type": "bar",
  "data_range": "B1:B10",
  "categories_range": "A2:A10",
  "title": "Monthly Revenue",
  "target_cell": "F2"
}

---

環境変数

変数	デフォルト	説明
XLSX_MCP_FILES	empty	起動時に事前読み込みする alias=path または path を、カンマまたはセミコロンで区切って指定します。
XLSX_MCP_ALLOWED_DIRS	empty	ファイルアクセスを制限するディレクトリを、カンマまたはセミコロンで区切って指定します（範囲外のパスにアクセスすると AccessDeniedError が発生します）。Windows では大文字と小文字を区別しない比較に対応しています。
XLSX_MCP_AUTO_BACKUP	true	ワークブックを変更する前に .bak コピーを自動作成します。
XLSX_MCP_BACKUP_DIR	empty	バックアップファイルの保存先ディレクトリです（デフォルトでは対象ファイルと同じ場所です）。
XLSX_MCP_RECALC_TIMEOUT	60	ヘッドレス LibreOffice で数式を再計算する際のタイムアウト（秒）です。
XLSX_MCP_LOCK_TIMEOUT	10	失敗するまでにファイルごとのロック取得を待つタイムアウト（秒）です。

---

セキュリティと並行処理

• パスの制限 — XLSX_MCP_ALLOWED_DIRS（カンマまたはセミコロン区切り）を設定すると、すべての読み取りと書き込みが特定のディレクトリ内に制限されます。設定されている場合、これらの範囲外にあるファイルへのアクセスを試みると AccessDeniedError が発生します。Windows では、大文字と小文字を区別しないパス比較と複数ドライブのパスに対応しています。
• 自動バックアップと復元 — backup=True の場合（デフォルトは XLSX_MCP_AUTO_BACKUP=true）、書き込みツールはワークブックを変更する前に、同じディレクトリに .bak ファイルを自動作成します。バックアップを特定のフォルダーに保存するには XLSX_MCP_BACKUP_DIR を使用します。変更をアトミックに元に戻すには restore_backup を使用します。
• 数式インジェクション対策 — write_cells と append_rows は、データの流出やコマンド実行を防ぐため、デフォルトで WEBSERVICE、HYPERLINK、INDIRECT、RTD、CALL、REGISTER を含む数式や、DDE コマンド（|）を拒否します。このチェックを回避するには allow_external_formulas=True を渡します。
• AST による安全なクエリ検証 — query_sheet は AST パーサーを使用し、比較、ブール演算、安全な演算子のみを厳密に許可します。これにより、@ による変数参照、コード実行を伴う呼び出し、非公開の dunder 属性をブロックします。
• XML 爆弾対策 — defusedxml はこのパッケージの依存関係として自動的にインストールされます。openpyxl はこれを自動検出して強化された XML パーサーを使用するため、悪意のある .xlsx（XML を ZIP 圧縮したファイル）によってエンティティ展開によるリソース枯渇が引き起こされることはありません。設定は不要です。
• ファイルごとのロック — すべての読み取り／書き込みで、同じディレクトリにある <path>.lock ファイル（filelock 経由）を取得します。同じワークブックにアクセスする並行したツール呼び出しや他のプロセスは順番に処理されるため、書き込みが交錯してファイルを破損することはありません。
• 一時的なロック違反への対応 — Windows NTFS では、ウイルス対策ソフトや検索インデクサーが保存直後のファイルを検査している間、アトミックなファイルの入れ替えで一時的に共有違反（WinError 32 / 33）が発生することがあります。サーバーは指数バックオフで再試行し、ロックが解除されると自動的に処理を続行します。ファイルが Microsoft Excel で恒久的に開かれている場合は、明確な案内メッセージを表示します。
• 再計算タイムアウト — XLSX_MCP_RECALC_TIMEOUT（秒、デフォルトは 60）は、LibreOffice による再計算処理の実行時間の上限を設定します。
• ロックタイムアウト — XLSX_MCP_LOCK_TIMEOUT（秒、デフォルトは 10）は、失敗するまでにツールがファイルごとのロック取得を待つ時間の上限を設定します。

---

トラブルシューティング

• 数式が壊れているのにerrors_foundが空です — 再計算が実行されなかった可能性があります。messageフィールドを確認してください。LibreOfficeが見つからなかったと表示される場合、ファイルはそのままopenpyxlで保存されており、数式は再計算されていません（キャッシュされた値が古い可能性があります）。LibreOfficeをインストールしてください（要件を参照）。
• 再計算に時間がかかる、またはタイムアウトします — XLSX_MCP_RECALC_TIMEOUTを増やしてください（デフォルトは60s）。タイムアウトしてもファイルは保存されますが、recalculatedはfalseになり、messageに再計算がタイムアウトしたと表示されます。
• 同時アクセス時にLockTimeoutErrorが発生します — 別の操作がロックを保持しています。XLSX_MCP_LOCK_TIMEOUTを増やす（デフォルトは10s）か、別の操作が完了してから再試行してください。
• Workbook is locked by another process / WinError 32 — Windowsでは、Microsoft Excelや一部のアプリケーションが開いているファイルを排他的にロックします。Excelでブックを閉じてから、再試行してください。ウイルス対策スキャナーや検索インデクサーによる一時的なロックは、サーバーが失敗する前に自動的に再試行します。
• 「シートが見つかりません」 — エラーメッセージに利用可能なシート名が表示されるので、正しいものを選択できます。
• pathが必要です／ファイルが設定されていません — pathを指定せずにツールを呼び出したものの、ファイルが事前に読み込まれていない（または複数読み込まれている）状態です。XLSX_MCP_FILESを使ってファイルを1つ事前に読み込むか、明示的なエイリアスを渡すか、パスを直接渡してください。

---

開発／コントリビューション

CONTRIBUTING.mdを参照してください。次のコマンドでテストスイートを実行します。

uv run pytest