excel-mcp

Excel MCP サーバーのスキル

Model Context Protocol を介して 326 個の Excel 操作を提供します。MCP サーバーは ExcelMCP Service をプロセス内でホストし、直接呼び出すことで、低遅延の Excel 自動化を実現します。ツールは自動検出されます。このドキュメントでは、特有の動作、ワークフロー、注意点について説明します。

ワークフローのチェックリスト

手順	ツール	アクション	タイミング
1. ファイルを開く	file	open または create	必ず最初に
2. シートを作成する	worksheet	create、rename	必要に応じて
3. データを書き込む	range	set-values	必ず実行（2D 配列）
4. 書式を設定する	range	set-number-format	書き込み後
5. 構造を設定する	table	create	データをテーブルに変換
6. 保存して閉じる	file	save: true を指定して close	必ず最後に

前提条件

• Microsoft Excel がインストールされた Windows ホスト（2016 以降）
• Windows のフルパスを使用します：C:\Users\Name\Documents\Report.xlsx
• Excel ファイルを別の Excel インスタンスで開いていないこと

計算モードのワークフロー（バッチ処理のパフォーマンス）

calculation_mode を使用して、一括書き込みのパフォーマンスを最適化します。多数の値や数式を書き込むときは、自動再計算を無効にして、セルごとの再計算を避けます：

1. calculation_mode(action: 'set-mode', mode: 'manual')  → Disable auto-recalc
2. Perform all writes (range set-values, set-formulas)
3. calculation_mode(action: 'calculate', scope: 'workbook')  → Recalculate once
4. calculation_mode(action: 'set-mode', mode: 'automatic')  → Restore default

注： 数式を読み取るだけなら、手動モードにする必要はありません。range get-formulas は計算モードに関係なく数式のテキストを返します。

重要：実行ルール（必ず守ること）

ルール 1：確認の質問をしない

停止してください。「どのファイルですか？」「どのテーブルですか？」「どこに配置すればよいですか？」と尋ねようとしているなら、尋ねてはいけません。

悪い例（質問する）	良い例（調べる）
「どの Excel ファイルを使えばよいですか？」	file(list) → 開いているセッションを使用する
「テーブル名は何ですか？」	table(list) → テーブルを確認する
「データがあるシートはどれですか？」	worksheet(list) → すべてのシートを確認する
「ピボットテーブルを作成しますか？」	はい — 新しいシートに作成する

自分で疑問に答えるためのツールがあります。必ず使ってください。

ルール 2：最後に必ずテキストで要約する

**ツール呼び出しだけでターンを終えてはいけません。**すべての操作が完了したら、実行内容を確認する簡潔なテキストメッセージを必ず返します。ツール呼び出しだけで応答を終えると不完全です。

ルール 3：データに適切な書式を設定する

値を設定した後は、必ず数値書式を適用します。

データ型	書式コード	結果
USD	$#,##0.00	$1,234.56
EUR	€#,##0.00	€1,234.56
パーセント	0.00%	15.00%
日付（ISO）	yyyy-mm-dd	2025-01-22

マシンのロケールに関係なく、書式コードは米国式の表記（桁区切りに ,、小数点に .）で記述します。Excel が変換します。表示される区切り記号は Windows の地域設定に従うため、ドイツ語のシステムでは $#,##0.00 が $1.234,56 と表示されます。書式コードの区切り記号を入れ替えて「修正」してはいけません。他のすべてのロケールで正しく動作しなくなります。

ワークフロー：

1. range set-values (data is now in cells)
2. range set-number-format (apply format)
3. range_format auto-fit-columns (formatted values are wider than raw ones)

手順 3 は省略できません。45678 に合わせた列幅では、値が 2025-01-22 や $1,234.56 と表示されると狭すぎるため、Excel は数値の代わりに ##### を表示します。

ルール 4：通常の範囲ではなく Excel テーブルを使用する

表形式のデータは必ず Excel テーブルに変換します。

1. range set-values (write data including headers)
2. table(action: 'create', table_name: 'SalesData', range_address: 'A1:D100')

理由： 構造化参照と自動拡張が利用でき、データモデルや DAX に必要です。

ルール 5：セッションのライフサイクル

1. file(action: 'open', path: '...')  → capture response.session_id as sessionId
2. workbook(action: 'get-info', session_id: sessionId)
3. file(action: 'close', session_id: sessionId, save: true)  → saves and closes

後続のセッションベースの呼び出しでは、同じ値を session_id として渡します。 上記の sessionId はローカル変数であり、MCP の引数名ではありません。file(list) のセッションを再利用する場合は、一致するエントリの sessionId の値を session_id にコピーします。セッションを推測したり、別のセッションで代用したりしてはいけません。

セッションを閉じ忘れると Excel プロセスが実行中のまま残り、ファイルがロックされます。

ルール 6：データモデルの前提条件

DAX 操作には、データモデル内のテーブルが必要です。

Step 1: Create table → Table exists
Step 2: table(action: 'add-to-data-model') → Table in Data Model
Step 3: datamodel(action: 'create-measure') → NOW this works

ルール 7：Power Query 開発ライフサイクル

ベストプラクティス：テストファーストのワークフロー

1. powerquery(action: 'evaluate', m_code: '...') → Test WITHOUT persisting
2. powerquery(action: 'create', ...) → Store validated query
3. powerquery(action: 'refresh', ...) → Load data

最初に評価する理由：

• 永続クエリを作成する前に、構文エラーやソースの不足を検出できます
• 作成／更新時の COM 例外よりも、わかりやすいエラーメッセージが表示されます
• 実際のデータプレビュー（列とサンプル行）を確認できます
• クリーンアップが不要です。M コード用の REPL のように使えます
• 単純なリテラルテーブルの場合のみ省略します

よくある間違い： 評価せずに作成／更新すると、ブックに壊れたクエリが残ります

ルール 8：削除して再構築するより、対象を絞って更新する

• 推奨：特定の範囲（例：5 行目の A5:C5）に set-values を使用します
• 避ける：構造全体を削除して再作成すること

理由： 書式、数式、参照を維持できます。

ルール 9：suggestedNextActions に従う

エラーレスポンスには、実行可能なヒントが含まれています：

{
  "success": false,
  "errorMessage": "Table 'Sales' not found in Data Model",
  "suggestedNextActions": ["table(action: 'add-to-data-model', table_name: 'Sales')"]
}

ツール選択のクイックリファレンス

タスク	ツール	主な操作
ブックの作成／オープン／保存	file	open、create、close
セルデータの書き込み／読み取り	range	set-values、get-values
セルの書式設定	range	set-number-format
データからテーブルを作成	table	create
Power Pivot にテーブルを追加	table	add-to-data-model
DAX 数式の作成	datamodel	create-measure
ピボットテーブルの作成	pivottable	create、create-from-datamodel
スライサーでフィルター	slicer	set-slicer-selection
グラフの作成	chart	create-from-range
What-if 分析の実行	analysis	goal-seek、create-scenario、create-data-table
計算モードの制御	calculation_mode	get-mode、set-mode、calculate
視覚的な確認	screenshot	capture、capture-sheet

リファレンスドキュメント

詳細なガイダンスについては、references/ を参照してください。

• What-if 分析と Solver の制限
• コア実行ルールと LLM ガイドライン
• 避けるべきよくある間違い
• 一括書き込みのパフォーマンス最適化
• データモデルの制約とパターン
• グラフと書式設定
• 条件付き書式の操作
• ダッシュボードとレポートのベストプラクティス
• データモデル／DAX の詳細
• データモデル分析用 DMV クエリリファレンス
• Excel エージェントモードと高度な自動化
• 注意点と既知の制限
• Power Query M コード構文リファレンス
• ピボットテーブルの操作
• Power Query の詳細
• 範囲の操作と数値書式
• スクリーンショットと視覚的な確認
• スライサーの操作
• テーブルの操作
• ウィンドウと表示状態の操作
• ワークシートの操作