excel-mcp-server

Excel MCP Server

Windows環境で起動中のExcelインスタンスに対して、VBAモジュールの追加・編集・実行を可能にするMCPサーバーです。

機能

コアツール

• get_workbooks: 現在起動しているExcelの全ワークブック一覧を取得
• list_modules: ワークブック内の全VBAモジュール一覧を取得
• get_module_code: 指定したモジュールのVBAコードを取得
• add_module: 新しいVBAモジュールを追加
• edit_vba: 既存のVBAモジュールのコードを編集
• run_macro: 指定したマクロを実行
• get_sheet_names: ワークブック内のシート名一覧を取得
• get_range_values: 指定した範囲のセル値を2次元配列で取得
• get_cell_value: 指定したセルの値・数式を取得
• read_immediate_window: VBAイミディエイトウィンドウの内容を読み取り（Debug.Print出力の確認）⚠️
• write_immediate_window: VBAイミディエイトウィンドウで式を評価（変数値の確認やテストコード実行）⚠️

AIアシスタント向けガイドライン（Prompts機能）

Excel MCP Serverは、AIアシスタントに対して使用方法のガイドラインを提供します：

• excel-vba-guidelines: エラーキャプチャパターン、イミディエイト操作の許可プロトコルなどの詳細なガイドライン

このガイドラインはMCPサーバー自体が提供するため、ユーザーによる追加設定は不要です。

⚠️ 注意が必要なツール

以下のツールはVBEウィンドウをアクティブにし、キーボード操作を送信するため、実行中は他の作業が中断される可能性があります。AIアシスタントは使用前にユーザーに確認します：

• read_immediate_window: VBEウィンドウをアクティブにし、Ctrl+G、Ctrl+A、Ctrl+Cのキー操作を送信し、クリップボードを使用します
• write_immediate_window: VBEウィンドウをアクティブにし、Ctrl+Gのキー操作、式の入力、Enterキーを送信します

前提条件

システム要件

• Windows OS
• Node.js 18以上
• Microsoft Excel（起動している必要があります）

Excelのセキュリティ設定

VBAプロジェクトにアクセスするには、Excelで以下の設定を有効にする必要があります：

1. Excelを開く
2. ファイル → オプション → トラストセンター → トラストセンターの設定
3. 「マクロの設定」を選択
4. 「VBAプロジェクトオブジェクトモデルへのアクセスを信頼する」 にチェックを入れる
5. OKをクリック

インストール

方法1: npx で直接使用（推奨・最も簡単）

クローン不要で、すぐに使えます：

Claude Desktop の設定ファイル（%APPDATA%\Claude\claude_desktop_config.json）に追加：

{
  "mcpServers": {
    "excel": {
      "command": "npx",
      "args": ["github:prizmPrograms/excel-mcp-server"]
    }
  }
}

メリット:

• ✅ インストール不要（ローカルにファイルを残さない）
• ✅ 常に最新版を使用
• ✅ 最も簡単

注意: 初回起動時は npx がパッケージをダウンロードするため少し時間がかかりますが、2回目以降はキャッシュが使われて高速になります。

---

方法2: ローカルにクローンして使用

より高速な起動やオフライン使用が必要な場合：

1. リポジトリをクローン

git clone https://github.com/prizmPrograms/excel-mcp-server.git
cd excel-mcp-server

または、ReleasesからZIPファイルをダウンロードして展開することもできます。

2. 依存関係をインストール

npm install

3. ビルド

npm run build

使い方

方法1を使用した場合（npx）

設定ファイルに追加後、Claude Desktop を再起動するだけです。自動的に起動します。

方法2を使用した場合（ローカルクローン）

MCPサーバーとして実行

node dist/index.js

MCP クライアント設定

Claude Desktop や他のMCPクライアントの設定ファイル（通常は %APPDATA%\Claude\claude_desktop_config.json）に以下を追加します：

{
  "mcpServers": {
    "excel": {
      "command": "node",
      "args": [
        "C:\\path\\to\\excel-mcp-server\\dist\\index.js"
      ]
    }
  }
}

注意: パスは絶対パスで指定してください。

ツールの使用例

ワークブック一覧の取得

get_workbooks

VBAモジュール一覧の取得

list_modules
- workbook: "Book1.xlsx"

VBAコードの取得

get_module_code
- workbook: "Book1.xlsx"
- module_name: "Module1"

新しいモジュールの追加

add_module
- workbook: "Book1.xlsx"
- module_name: "MyModule"
- module_type: 1  # 1=標準モジュール、2=クラスモジュール

VBAコードの編集

edit_vba
- workbook: "Book1.xlsx"
- module_name: "Module1"
- code: |
    Sub HelloWorld()
        MsgBox "Hello, World!"
    End Sub

マクロの実行

run_macro
- workbook: "Book1.xlsx"
- macro_name: "Module1.MyMacro"

エラーキャプチャパターン（デバッグ時）

AIアシスタントは、マクロのデバッグ時に自動的にエラーキャプチャパターンを使用します。このパターンは、一時的なVBAラッパー関数を生成してエラー情報をキャプチャします。

パターンの仕組み:

1. 一時モジュール（例: _ErrorCapture_1234567890）を作成
2. エラーキャプチャ用のラッパー関数を追加
3. run_macroでラッパー関数を実行
4. JSON形式でエラー情報を取得: {"status":"error","number":13,"description":"Type mismatch"...}
5. エラー情報を基にコードを修正
6. 一時モジュールをクリーンアップ

主なVBAエラー番号:

• 5: 無効なプロシージャ呼び出し
• 6: オーバーフロー
• 9: インデックスが有効範囲にありません（配列）
• 11: 0で除算
• 13: 型が一致しません
• 91: オブジェクト変数が設定されていません
• 424: オブジェクトが必要です
• 1004: アプリケーション定義またはオブジェクト定義のエラー

詳細な使用方法は、AIアシスタントが提供するexcel-vba-guidelinesプロンプトに記載されています。

シート名一覧の取得

get_sheet_names
- workbook: "Book1.xlsx"

レスポンス例: ``json [ {"Name": "Sheet1", "Index": 1, "Visible": -1}, {"Name": "Sheet2", "Index": 2, "Visible": -1}, {"Name": "Hidden", "Index": 3, "Visible": 0} ] ``

セル範囲の値取得

get_range_values
- workbook: "Book1.xlsx"
- sheet: "Sheet1"
- range: "A1:C3"

レスポンス例: ``json { "WorkbookName": "Book1.xlsx", "SheetName": "Sheet1", "RangeAddress": "A1:C3", "RowCount": 3, "ColumnCount": 3, "Values": [ [1, 2, 3], [4, 5, 6], [7, 8, 9] ] } ``

単一セルの値取得

get_cell_value
- workbook: "Book1.xlsx"
- sheet: "Sheet1"
- cell: "A1"

レスポンス例: ``json { "WorkbookName": "Book1.xlsx", "SheetName": "Sheet1", "Address": "$A$1", "Value": 100, "Text": "100", "Formula": "=SUM(B1:B10)", "HasFormula": true } ``

イミディエイトウィンドウでの式評価

write_immediate_window
- workbook: "Book1.xlsx"
- expression: "arrFrom(1, 2, 3)"

この機能は、VBA関数の戻り値を確認したり、変数の内容を確認したりするのに便利です。 式は ? プレフィックス付きで評価され、結果がイミディエイトウィンドウに表示されます。

イミディエイトウィンドウの内容読み取り

read_immediate_window
- workbook: "Book1.xlsx"

レスポンス例: ``json { "Success": true, "Content": "Array 1: dim=1 size=(3) lbs=(0) data=[1,2,3]\nArray 2: dim=1 size=(3) lbs=(0) data=[4,5,6]", "LineCount": 2 } ``

AIによるVBA自動デバッグ

AIアシスタントは、マクロのエラー時に自動的にデバッグと修正を行います：

エラーキャプチャパターンによる自動修正フロー:

1. エラーキャプチャパターン実行 → 詳細なエラー情報取得（ErrorNumber + ErrorDescription）
2. get_module_code → 問題のVBAコードを取得
3. AI がエラーを解析して修正コードを生成
4. edit_vba → 修正コードをモジュールに書き込む
5. エラーキャプチャパターン再実行 → 成功するまでループ

詳細な実装方法は、AIアシスタントが利用するexcel-vba-guidelinesプロンプトに記載されています。

移行ガイド（v2.0.0）

🔄 run_macro_safe の削除について

v2.0.0で変更: run_macro_safeツールは削除されました。

代替方法: AIアシスタントは、MCPのPrompts機能で提供されるexcel-vba-guidelinesプロンプトに基づき、エラーキャプチャパターンを実装します。

このパターンは以下のツールを組み合わせて実現されます：

• add_module: 一時モジュール _ErrorCapture_<timestamp> の作成
• edit_vba: エラーキャプチャラッパー関数の追加
• run_macro: ラッパー関数の実行でJSON形式のエラー情報を取得

変更の利点:

• ✅ 透明性: 何が起きているか明確（一時モジュールが作成される）
• ✅ 柔軟性: 必要に応じてカスタマイズ可能
• ✅ 保守性: ガイドラインはMCPサーバーに含まれ、自動更新される
• ✅ 拡張性: 将来的に他のガイドラインも追加可能

ユーザーへの影響:

• 既存のツール（add_module, edit_vba, run_macro）はすべて引き続き利用可能
• AIアシスタントの動作は変わらず、より明確になります
• 追加の設定は不要（npx excel-mcp-serverで自動的に利用可能）

トラブルシューティング

Excelが認識されない

症状: get_workbooks が空の配列を返す、または "Excel is not running" エラー

解決方法:

1. Excelが実際に起動しているか確認
2. 管理者権限でExcelを起動している場合、MCPサーバーも管理者権限で実行する必要があります
3. PowerShellの実行ポリシーを確認: Get-ExecutionPolicy（RemoteSignedまたはUnrestrictedが必要）

VBAプロジェクトにアクセスできない

症状: "Programmatic access to Visual Basic Project is not trusted"

解決方法:

1. Excelを開く
2. ファイル → オプション → トラストセンター → トラストセンターの設定
3. 「マクロの設定」を選択
4. 「VBAプロジェクトオブジェクトモデルへのアクセスを信頼する」にチェック

イミディエイトウィンドウ操作が失敗する

症状: read_immediate_window または write_immediate_window がタイムアウトまたはエラー

解決方法:

1. Excelウィンドウが他のウィンドウに隠れていないか確認
2. VBEエディタが既に開いている場合は閉じる
3. 実行中に他のキーボード操作を行わない
4. セキュリティソフトがキーボード操作をブロックしていないか確認

ビルドエラー

症状: npm run build がエラーを出す

解決方法:

1. Node.jsのバージョン確認: node --version（18以上が必要）
2. node_modules を削除して再インストール: rm -r node_modules; npm install
3. TypeScriptのグローバルインストール: npm install -g typescript

ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。

作者

prizmPrograms

貢献

バグ報告や機能リクエストは Issues でお願いします。

プルリクエストも歓迎します！

シート名一覧の取得

get_sheet_names
- workbook: "Book1.xlsx"

セル範囲の値を取得（VBA実行結果の読み出しに活用）

get_range_values
- workbook: "Book1.xlsx"
- sheet: "Sheet1"
- range: "A1:C10"

単一セルの値・数式を取得

get_cell_value
- workbook: "Book1.xlsx"
- sheet: "Sheet1"
- cell: "A1"

VBAからAIへのデータ受け渡しパターン

パターン1: VBA Functionの戻り値を使う（単純な値）

Function GetSummary() As String
    GetSummary = "処理完了: " & Cells(1,1).Value
End Function

run_macro
- workbook: "Book1.xlsx"
- macro_name: "Module1.GetSummary"

→ Result フィールドに戻り値が入る

パターン2: VBAがセルに書き込み → AIが読み取る（複雑なデータ）

Sub CalcAndWrite()
    Dim result As Double
    result = 複雑な計算...
    Worksheets("Output").Cells(1, 1).Value = result
End Sub

1. run_macro → Module1.CalcAndWrite
2. get_cell_value → sheet: "Output", cell: "A1"

デバッグ機能

AIが自律的にVBAコードをテスト・デバッグできる機能を提供します。

イミディエイトウィンドウの読み取り

VBAのDebug.Print出力やテスト結果を確認できます。

read_immediate_window
- workbook: "Book1"

使用例: ``vba Sub TestFunction() Debug.Print "Test 1: "; AddNumbers(2, 3) Debug.Print "Test 2: "; AddNumbers(-1, 1) End Sub ``

マクロ実行後にread_immediate_windowを呼び出すと、Debug.Print出力を取得できます。

イミディエイトウィンドウで式を評価

変数の値を確認したり、テスト式を実行したりできます。

write_immediate_window
- workbook: "Book1"
- expression: "AddNumbers(10, 20)"

式の例:

• myVariable - 変数の値を確認
• 1+1 - 簡単な計算
• MyFunction(5) - 関数を呼び出して結果を確認
• Cells(1,1).Value - セルの値を確認

仕組み: 一時マクロを生成して式を評価し、結果をDebug.Printで出力します。

制限事項

複数のExcelプロセスについて

このMCPサーバーは、単一のExcelプロセス内のすべてのワークブックにアクセスできます。

ただし、複数のExcel.exeプロセスが同時に起動している場合（Excelを複数の独立したウィンドウで起動した場合）、Windows COMの制限により、通常は最初に起動したExcelプロセスのみがアクセス可能です。

推奨される使用方法

• すべてのExcelファイルを同じExcelインスタンス（同じプロセス）で開いてください
• 通常、Excelファイルをダブルクリックして開くと、既存のExcelプロセスで開かれます
• 新しいExcelプロセスは、明示的に「新しいウィンドウ」を開いた場合のみ起動します

複数プロセスが起動している場合

もし複数のExcelプロセスが起動していて、特定のブックにアクセスできない場合：

1. 対象のブックを閉じる
2. 既存のExcelウィンドウから「ファイル → 開く」で再度開く
3. これにより、同じプロセス内で開かれ、アクセス可能になります

AIによる自律的なテスト/デバッグワークフロー

これらの機能を組み合わせて、AIが自動的にVBAコードをテスト・検証できます：

パターン1: 自動テスト実行

1. edit_vba → テスト対象の関数を作成
2. edit_vba → テストマクロを作成（Debug.Printで結果を出力）
3. run_macro → テストマクロを実行
4. read_immediate_window → テスト結果を読み取り
5. AIが結果を解析して成功/失敗を判定
6. 失敗している場合は修正して再テスト（ステップ1に戻る）

テストマクロの例: ``vba Sub TestAddNumbers() Debug.Print "Test 1: "; (AddNumbers(2, 3) = 5) Debug.Print "Test 2: "; (AddNumbers(-1, 1) = 0) Debug.Print "Test 3: "; (AddNumbers(0, 0) = 0) End Sub ``

パターン2: 式の評価によるテスト

1. edit_vba → 関数を作成
2. write_immediate_window → 関数を呼び出して結果を確認
3. read_immediate_window → 結果を読み取り
4. AIが期待値と比較して判定
5. 必要に応じて修正

例: `` write_immediate_window -expression: "AddNumbers(5, 10)" read_immediate_window → "15" が出力されていることを確認 ``

技術詳細

アーキテクチャ

このMCPサーバーは以下のコンポーネントで構成されています：

1. excel-com.ps1: PowerShellスクリプトでExcel COMオブジェクトを直接操作
2. excel-wrapper.ts: PowerShellスクリプトを呼び出すTypeScriptラッパー
3. index.ts: MCPサーバーのメインエントリーポイント

なぜPowerShellを使用するのか？

Node.jsから直接Windows COM オブジェクトを操作するには、ネイティブモジュール（winaxなど）が必要ですが、これらはVisual Studio Build Toolsを必要とします。PowerShellを使用することで、追加のビルドツールなしでCOM操作が可能になります。

モジュールタイプ

• 1: 標準モジュール（VBAコード用）
• 2: クラスモジュール
• 3: ユーザーフォーム

トラブルシューティング

Excelが認識されない

症状: get_workbooks が空の配列を返す、または "Excel is not running" エラー

解決方法:

1. Excelが実際に起動しているか確認
2. 管理者権限でExcelを起動している場合、MCPサーバーも管理者権限で実行する必要があります
3. PowerShellの実行ポリシーを確認: Get-ExecutionPolicy（RemoteSignedまたはUnrestrictedが必要）

VBAプロジェクトにアクセスできない

症状: "Programmatic access to Visual Basic Project is not trusted"

解決方法:

1. Excelを開く
2. ファイル → オプション → トラストセンター → トラストセンターの設定
3. 「マクロの設定」を選択
4. 「VBAプロジェクトオブジェクトモデルへのアクセスを信頼する」にチェック

イミディエイトウィンドウ操作が失敗する

症状: read_immediate_window または write_immediate_window がタイムアウトまたはエラー

解決方法:

1. Excelウィンドウが他のウィンドウに隠れていないか確認
2. VBEエディタが既に開いている場合は閉じる
3. 実行中に他のキーボード操作を行わない
4. セキュリティソフトがキーボード操作をブロックしていないか確認

ビルドエラー

症状: npm run build がエラーを出す

解決方法:

1. Node.jsのバージョン確認: node --version（18以上が必要）
2. node_modules を削除して再インストール: rm -r node_modules; npm install
3. TypeScriptのグローバルインストール: npm install -g typescript

PowerShell実行ポリシーエラー

スクリプトは -ExecutionPolicy Bypass で実行されるため、通常は問題ありませんが、エラーが発生する場合は管理者権限でPowerShellを開き： ``powershell Set-ExecutionPolicy RemoteSigned -Scope CurrentUser ``

制限事項

• Windows専用（COM経由のため）
• Excelが既に起動している必要がある
• VBAプロジェクトへのアクセスにはセキュリティ設定の変更が必要

ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。

作者

prizmPrograms

貢献

バグ報告や機能リクエストは Issues でお願いします。

プルリクエストも歓迎します！