XLIDE

xlide-mcp

Office ファイルの内部を扱う MCP サーバーです。 Excel、Word、PowerPoint、Access の VBA を読み取り、書き込み、分析、テストし、その周囲にあるドキュメントも編集できます。Visual Basic 6 プロジェクトも同じ方法で開けます。

VBA、Power Query、OOXML ワークシートの編集には Office のインストールは不要で、Windows、macOS、Linux で動作します。.xlsb と .xls のセルの読み取り、.xlsb のセルへの書き込み、マクロやテストの実行には、デスクトップアプリを備えた Windows が必要です。

xlide_list_projects                -> Budget.xlsm
xlide_project_info   Budget.xlsm   -> 4 modules, 2 sheets, 1 query, not signed
xlide_read_module    Helpers       -> the source, and a content token
xlide_write_module   Helpers       -> guarded by that token
xlide_analyze        Budget.xlsm   -> 0 errors, 2 warnings
xlide_run_tests      Budget.xlsm   -> 12 passed

理由

マクロの修正を依頼されたエージェントは、プロジェクトのほかの部分を把握できないまま、コピーされたコード断片をもとに作業するか、ユーザーにモジュールをエクスポートしてもらい、作業後に貼り戻すよう求めます。どちらも Office ファイルを中身の分からないものとして扱っています。VBA プロジェクト、フォームのデザイン、M コードは、アプリケーションを開かなくてもすべて読み書きできます。

このサーバーにより、それらを利用できるようにしつつ、操作に制限を設けます。読み取り後にモジュールが変更されている場合、書き込みは拒否されます。分析エラーが発生すると、変更は失敗します。実行はサーバーが作成し、期限を設定したアプリケーション内で行われます。元に戻せない操作を行うかどうかは、ユーザーが決めます。

実装

ディレクトリ	言語	ステータス
python/	Python 3.10+	リファレンス実装

ほかの言語の実装は、兄弟ディレクトリに配置します。Python を基準とし、上流ライブラリの変更を追跡します。各移植版は Python に準拠します。docs/porting.md を参照してください。

インストールと実行

pip install xlide-mcp              # reads and writes files, any platform
pip install "xlide-mcp[live]"      # adds running macros and tests, Windows
xlide-mcp --root /path/to/your/files

クライアントから接続します。Claude Desktop、Claude Code、または stdio 経由でサーバーを起動する任意のクライアントの場合：

{
  "mcpServers": {
    "xlide": {
      "command": "xlide-mcp",
      "args": ["--root", "/path/to/your/files"]
    }
  }
}

VS Code の場合は、ワークスペースのルートにある .vscode/mcp.json に次の設定を記述します。ここでは VS Code が servers を使用します。上記のポータブルな .mcp.json 形式では mcpServers を使用します。

{
  "servers": {
    "xlide": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "xlide-mcp[live]", "xlide-mcp", "--root", "${workspaceFolder}"]
    }
  }
}

VS Code で MCP: List Servers を実行して xlide を起動します。登録されない場合は、出力を確認してください。サーバーは起動時にバージョンと許可されたルートを stderr に出力します。VS Code の設定形式とコマンドについては、VS Code の MCP ガイドで説明されています。

または、何もインストールせず、初回実行時に uv に取得させることもできます。uv は単一のバイナリで、独自の Python をインストールするため、どちらもインストールされていないマシンでも次のコマンドを実行できます：

{
  "mcpServers": {
    "xlide": {
      "command": "uvx",
      "args": [
        "--from", "xlide-mcp[live]",
        "xlide-mcp", "--root", "/path/to/your/files"
      ]
    }
  }
}

live エクストラはどのプラットフォームでも安全に指定できます。取得するものには sys_platform == 'win32' のマークが付いているため、Windows 以外では何も解決されず、同じ設定をどこでも使用できます。ファイルレイヤーのみを使う場合は、--from の組を削除してください。uvx はバージョンを固定しない限り、最新の公開バージョンを使用します（例：[email protected]）。

ファイルレイヤー用の Dockerfile があります。このレイヤーは Office のインストールを必要としません。コンテナのアクセス範囲を制限するルートにするため、ファイルを含むフォルダーを /workspace にマウントしてください：

docker build -t xlide-mcp .
docker run --rm -i -v "$PWD:/workspace" xlide-mcp

--root はセキュリティ境界です。ツールが受け付けるすべてのパスは、シンボリックリンクも含めて解決され、ルート内にない場合は拒否されます。読み取りと分析のみを許可し、すべての書き込みを拒否するには、--read-only を追加してください。

新しいクライアントからは、まず xlide_doctor を呼び出してください。ワークスペースのルート、インストールされているレイヤー、このマシンにある Office アプリケーション、および各アプリケーションでモジュールインジェクションに必要なトラストセンター設定が有効かどうかが報告されます。

機能

ファイル - VBA プロジェクトと、それを含むドキュメントです。ほとんどのファイルツールは Office のインストールを必要としません。バイナリ形式の Excel グリッドには Windows 上の Excel が必要です。

コードプロジェクト

検出	xlide_list_projects、xlide_project_info、xlide_validate_project、xlide_create_project、xlide_doctor
モジュール	xlide_list_modules、xlide_read_module、xlide_write_module、xlide_edit_module、xlide_rename_module、xlide_delete_module、xlide_list_procedures、xlide_search_modules
分析	xlide_analyze、xlide_analyze_source、xlide_rules
フォーム	xlide_list_forms、xlide_read_form、xlide_manage_form、xlide_edit_form
参照とカタログ	xlide_list_references、xlide_manage_reference、xlide_access_catalog、xlide_read_access_query
ソース管理	xlide_export_modules、xlide_import_modules、xlide_git_changes
xlide_edit_module は preview_only=true を指定すると、複数の行編集を確認し、保存せずに変更案の差分を返します。プレビューのコンテンツトークンは、モジュールに変更がなければ、同じ編集を適用するために使用できます。
xlide_search_modules は一致したモジュールのトークンを返すため、その行番号をガード付き編集に直接渡すこともできます。
広範囲の検索は offset と next_offset を使ってページ分割できます。total_match_count は、すべてのページにわたる一致行数を示します。
xlide_list_procedures は、一覧に表示された行をガード付き編集するためのコンテンツトークンを返します。空のモジュールを読み取ると、空の本文とトークンが返されます。
モジュールに同一の内容を書き込む場合や、変更のないモジュールのインポートを適用する場合、保存はスキップされます。応答には saved=false と表示されます。
変更のないエクスポートを適用しても、既存の .bas ファイルと .cls ファイルは変更されません。
長い Power Query 数式は行単位で読み取れます。読み取り時に返されるトークンを使うことで、xlide_write_query は古くなった変更を拒否できます。
大きなフォーム設計は、offset と next_offset を使ってページ分割して読み取れます。
Office ファイル、VBA モジュール、Power Query の一覧でも、後続ページがある場合は next_offset が返されます。
図形が密集したレイヤーでは、xlide_list_shapes に sheet を渡し、next_offset を使って後続の図形を読み取ります。
ワークシート一覧では、読み取れない表示状態やピボットのメタデータは不明として示されます。また、書式付きセルやリッチテキストのセルの読み取りでデコードに失敗した場合は、空白を返す代わりにセル名が示されます。
Excel を使用したワークシートの調査では、不正な出力を破棄する代わりにエラーとして返します。
Excel を使用したセルの読み取りでは、部分的なグリッドを全範囲として示す代わりにエラーとして返します。
フォームの概要一覧でも、同じ offset と next_offset によるページ分割を使用します。
フォームの読み取りでは、プロパティやセクションが存在しない場合と読み取りに失敗した場合を区別します。また、Access レポートのコレクションを読み取れない場合は、空として表示せずエラーになります。
長いモジュールのプロシージャ一覧でも、next_offset が返されます。
構造検証の問題は、offset と next_offset を使って読み取れます。
Access カタログの一覧では、含まれる各コレクションに対して next_offsets エントリが返されます。
保存済みクエリの長い SQL はカタログ内でプレビューされます。xlide_read_access_query は、コンテンツトークンとともに全文を文字数単位のページで返します。
テーブル、名前、検証、条件付き書式、ハイパーリンク、コメントの list アクションでも、offset と max_results を指定でき、next_offset が返されます。
セルを結合すると、左上の値だけが残ります。allow_overwrite=true を指定しない限り、xlide_format_cells は他の値や数式の消去を拒否します。
xlide_sort_rows は、順序付きキーを使って範囲、テーブル、またはフィルターを並べ替えます。xlide_remove_duplicates は、最初に一致した行を残します。xlide_copy_cells は、形式を選択して貼り付けるオプションを使ってシート間でコピーし、allow_overwrite=true の指定が必要です。
xlide_update_shape は図形を削除せずに、位置、名前、テキスト、代替テキスト、表示状態を変更します。また、フォームコントロールのリンク先セルやリスト範囲も変更します。

xlide_check_cells は、テキストとして保存された数値や一貫性のない数式など、Excel の緑色の三角形で示されるエラーチェック項目を一覧表示します。一覧が長い場合はページ分割できます。

周辺のドキュメント

Power Query	xlide_list_queries、xlide_read_query、xlide_write_query（設定、名前変更、削除、読み込み、読み込み解除）
シートとセル	xlide_list_sheets、xlide_read_cells、xlide_write_cells、xlide_evaluate_formula、xlide_check_cells、xlide_format_cells、xlide_sort_rows、xlide_remove_duplicates、xlide_copy_cells
構造	xlide_manage_sheet、xlide_manage_rows_columns
テーブルと名前	xlide_manage_table、xlide_manage_name、xlide_manage_filter
ルール、リンク、メモ	xlide_manage_validation、xlide_manage_conditional_format、xlide_manage_hyperlink、xlide_manage_comment、xlide_page_setup
図形とグラフ	xlide_list_shapes、xlide_manage_shape、xlide_update_shape、xlide_set_shape_macro、xlide_add_chart

実行 - デスクトップアプリを使用する Windows。

xlide_run_macro、xlide_run_vba、xlide_run_tests、xlide_compile_check Office アプリケーション - デスクトップアプリケーションを備えた Windows。このサーバーがユーザーの実行中のアプリケーション内で動作する唯一の場所であり、指定されたファイルだけを対象にします。

xlide_is_open, xlide_open_in_app, xlide_close_in_app

ライブエディター - Visual Basic Editor 内で実行中の xlide_vbide セッションです。

xlide_live_sessions, xlide_live_state, xlide_live_request, xlide_live_read_module

xlide_live_read_module は、長い未保存のソースに対して行範囲を指定でき、そのソースと保存済みモジュールを比較するためのコンテンツトークンを返します。 どちらの分析ツールも、検出結果が1ページを超えると next_offset を返しますが、重要度ごとの合計数はすべて保持します。

フォーマット

ホスト	拡張子
Excel	.xlsm .xlsb .xlam .xls、および VBA 以外のすべてを対象とする .xlsx
Word	.docm .dotm .doc
PowerPoint	.pptm .potm
Access	.accdb .mdb
Visual Basic 6	.vbp

VBA はいずれのファイルでも読み取りと書き込みができます。Power Query は .xlsx、.xlsm、.xlsb、.xlam で利用でき、パッケージベースのワークシート編集は .xlsx、.xlsm、.xlam で利用できます。.xlsx には仕様上 VBA プロジェクトがありませんが、クエリとシートにはすべてアクセスできるため、ここに記載されています。

これらの拡張子以外でも認識可能な拡張子は、開けない理由とともに一覧表示されます。理由を示さず一覧から項目が消えることはありません。

Excel、Word、PowerPoint は、最初のマクロが存在するまで、マクロ有効ファイルに VBA プロジェクトを書き込みません。そのため、まだコードが書かれていない .xlsm には VBA プロジェクトがありません。これは通常のファイルです。一覧では空の結果が返され、最初のモジュールを書き込むと、そのアプリケーションが作成するはずだったプロジェクトが作成されます。 コードを一度も保持したことのない Access データベースにも、プロジェクトがない場合があります。xlide_write_module は最初のモジュールとともにプロジェクトを作成し、xlide_create_project は既存の .accdb に空のプロジェクトを追加します。

.xlsb はグリッドをバイナリレコードに保持し、.xls は複合ファイル内に保持します。どちらも OOXML ではありません。Excel を使用する Windows では、これらのファイルは Excel 経由で処理されます。値はブックを開くことで生成されるため、結果には source: excel と recalculated: true が示されます。 この方法では値のみが返されます。このサーバー経由で .xls のセルに書き込むことはできません。

変更内容の確認

Office ファイルは git から見ると 1 つのバイナリ blob なので、VBA の 1 行を変更したコミットも、プロジェクト全体を置き換えたコミットも、同じ 3 つの単語で表されます：Binary files differ。どちらの場合も、同じレンダラーを通してファイルを読み取る 2 つの方法があります。

xlide_git_changes は、任意のリビジョンからの変更内容を、モジュールとクエリごとに 1 件ずつ、統一 diff 付きで報告します。コミット前や、エージェントが行った変更を確認するときに呼び出します。

xlide-mcp --textconv は git の textconv ドライバーです。一度設定すると、git が参照する場所すべてで、ファイルがテキストとして diff 表示されます。

echo '*.xlsm binary diff=vba' >> .gitattributes
git config diff.vba.textconv "xlide-mcp --textconv"
git config diff.vba.cachetextconv true

 Public Sub Greet()
-    MsgBox "hello"
+    MsgBox "hello, world"
+    Debug.Print Now
 End Sub

これが .xlsm に対する git diff です。git show と git log -p でも変換されます。

VS Code で XLIDE と並べて使う場合、3 つ目の方法もあります。書き込みのたびに、実行中の XLIDE に変更内容が通知されます。また、モジュールの書き込みには変更前と変更後の内容が含まれるため、XLIDE はプロジェクトツリーでそのモジュールにエージェントによる編集の印を付け、diff を開き、XLIDE 自身のエージェントツールと同様に「Keep」と「Revert」を提示します。この機能には、この通知を受け取る XLIDE が必要です。プロトコルについては docs/xlide-vscode-bridge.md を参照してください。 XLIDE が実行されていなければ、何も変わりません。

diff=vba だけでなく、binary diff=vba を指定してください。binary マクロは -diff -merge -text を意味し、その後の diff=vba は -diff だけを上書きします。そのため、ファイルには -text が維持され、git が破損の原因となるコンテナーに行末変換を適用することはありません。

VS Code では、git の履歴から取得した diff の左右いずれの内容も、このドライバーを通してレンダリングされます。これは git 拡張機能が blob を git show --textconv で読み取るためです。そのため、ワークブックの 2 つのリビジョンを比較すると、VBA が表示されます。一方、ソース管理パネルの作業ツリー diff には表示されません。右側にはディスク上のファイルがそのまま表示され、バイナリのままです。

どちらの方法でも、VBA、Power Query、シートの一覧がレンダリングされます。セルの値は含まれません。レンダリングされたすべてのファイルの 1 行目にその旨が記載されています。対象範囲を知らない人が、空の diff をワークブックに変更がなかったものと受け取るのを防ぐためです。どちらの方法でも、git は blob をそのまま保存するため、マージはバイナリのまま行われます。

動作の基本ルール

これらのルールはサーバー独自の指示に含まれているため、ユーザーが何も設定していなくても、接続したすべてのエージェントが読み込みます。

• ファイル内の VBA だけが、そのファイルの唯一の信頼できる情報源です。エクスポートされた .bas ファイルや .cls ファイルはコピーであり、古くなる可能性があります。
• 読み取りではコンテンツトークンが返されます。書き込み時にそのトークンを渡すと、その間にモジュールが変更されていた場合、書き込みは拒否されます。
• 変更のたびに分析を実行し、エラーがあればビルド失敗として扱います。
• 実行はサーバーが作成した Office インスタンスで行われるため、終了させることができます。ユーザー自身のアプリケーションに触れるのは上記の 3 つのツールを通じてのみで、対象として指定されたファイルに限られます。保存または破棄を指示する呼び出しの場合にのみ未保存の作業を閉じ、プロセスの終了は要求された場合にのみ行います。また、Windows がそのファイルを保持していると特定したプロセスだけを終了します。
• 元に戻すのが難しい操作は、ユーザーの判断に委ねられます。モジュールの削除、データを保持するセルの上書き、署名済みまたはパスワード保護されたプロジェクトへの書き込みが該当します。セルの上書きと、署名済みまたは保護されたプロジェクトへの書き込みは、それらを許可するフラグを呼び出しで渡すまで拒否されます。
• セルの値は、Excel が最後に計算した値です。ここで数式を書き込んでも、Excel が次に開くまでファイル内に結果は保存されません。calculate=true を指定すると、pyOfficeEditor's の数式エンジンで結果を算出し、計算できなかったセルを特定します。

セキュリティ

脆弱性は公開の issue ではなく、非公開の脆弱性報告から報告してください。SECURITY.mdには、報告に含める内容と修正が提供されるバージョンが記載されています。

CodeQL と Semgrep がサーバーとリリースのワークフローをスキャンし、pip-audit が実行時依存関係をチェックします。また、YARA Forge のルールを使う ClamAV と YARA-X が、追跡対象の全ファイルとビルド済みの wheel および sdist を、プッシュ、プルリクエスト、毎日の実行、リリースのたびにスキャンします。予期しない検出結果、スキャンの警告、またはスキャンの未実施があると、リリースは停止します。リリースが正常に完了すると、セキュリティレポートと SARIF の結果がダウンロード可能なアセットとして付属します。Dependabot は、レビュー用に依存関係とワークフローの更新を提案します。

構成要素

pyOpenVBA	Office ファイル内の VBA、UserForms、Power Query を純粋な Python で読み書きします。
pyOfficeEditor	セル、数式、書式設定、テーブル、入力規則、行、列を扱うドキュメントサーフェスです。
pyVBAanalysis	静的アナライザーです。各ホストのオブジェクトモデルに照らして測定された、165 個の診断項目があります。
pyVBAharness	期限を厳守させる監督プロセスのもと、デスクトップ版 Office で VBA を実行します。
XLIDE for VS Code	ツールサーフェス、コンテンツトークンガード、エージェントへの指示の提供元です。
xlide for the VBE	xlide_live_* ツールが通信する、ライブエディターセッションです。

コントリビュート

cd python
pip install -e ".[dev,live]"
python -m pytest              # the file layer, no Office needed
python -m pytest -m live      # the rest, real Office, Windows only
python -m ruff check src tests tools

contract/ 配下の生成されたコントラクトは常に最新の状態に保つ必要があります。最新でない場合、テストスイートは失敗します。ツールを変更した後は、次の操作を行ってください。

python tools/export_contract.py
python tools/export_conformance.py

ライセンス

MIT。