0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

OfficeCLI入門 — Excel数式を自動評価するAI向けCLIの仕組み

0
Last updated at Posted at 2026-07-20

はじめに

AIエージェントに Excel の集計表を作らせようとすると、大抵は「Excel がインストールされている前提」か「openpyxl で頑張って XML を組み立てる」の二択になる。どちらもエージェントが自律的に業務ドキュメントを触る用途にはやや重い。

OfficeCLI は、この隙間を埋めるために作られた OSS の CLI ツールだ。Word・Excel・PowerPoint を Office 未インストールの環境でも読み書きでき、単一バイナリで動く。Apache 2.0 ライセンスで公開されており、GitHub スター数は 19.6k（2026年7月時点）に達している。

この記事では、実際に npm install してクラウド環境で xlsx / docx / pptx を操作し、数式評価やパス指定の挙動を確認した結果を報告する。

この記事で学べること

  • OfficeCLI のインストールと基本コマンドの使い方
  • Excel 数式が Excel を起動せずに自動評価される仕組み
  • パス指定でハマったポイントと正しい書き方
  • AIエージェント（Claude Code など）への組み込み方法

対象読者

  • AIエージェントに業務ドキュメント操作をさせたい方
  • openpyxl / python-docx の代替を探している方
  • CLI から Office ファイルを CI/CD に組み込みたい方

TL;DR

  • OfficeCLI は単一バイナリの CLI で、Office 未インストールでも .docx / .xlsx / .pptx を読み書きできる
  • Excel の数式は追加した直後に自動計算され、get コマンドで computedValue として取得できる（実機確認）
  • パス指定は /sheet[1]/cell[B4] のような角括弧インデックス記法ではなく /Sheet1/B4 という A1参照そのままの記法を使う
  • officecli mcp で MCP サーバーとしても起動でき、officecli skills で Claude Code などに自身のスキル定義を自動登録する

インストールと基本操作

npm でグローバルインストールできる。

npm install -g @officecli/officecli

実際にクラウド環境（Linux）で実行したところ、以下のバージョンが入った。

$ officecli --version
1.0.139

GitHub の最新リリースも v1.0.139（2026-07-19）であり、npm 経由でも最新版が即座に取得できることを確認した。Homebrew（brew install officecli）・Scoop（Windows）でも配布されているが、依存関係が一切ないため CI コンテナへの組み込みも容易だ。

コマンド体系はシンプルで、create / add / set / get / query / remove / view の動詞ベースになっている。

officecli create budget.xlsx --json

ドキュメントを開くと内部でレジデントプロセスが常駐し（open コマンド相当）、以降の操作は再読み込みなしで高速に処理される。作業が終わったら close で明示的にファイルへフラッシュする。

Excel数式は開かずに自動評価される

OSSツールとしての差別化ポイントは、独自のフォーミュラエンジンを内蔵している点にある。350以上の Excel 関数をサポートし、書き込み時点で即座に計算する。

実際にセルを追加して確認した。

officecli add budget.xlsx /Sheet1 --type cell --prop ref=A1 --prop value="項目" --json
officecli add budget.xlsx /Sheet1 --type cell --prop ref=B1 --prop value="金額" --json
officecli add budget.xlsx /Sheet1 --type cell --prop ref=A2 --prop value="サーバー" --json
officecli add budget.xlsx /Sheet1 --type cell --prop ref=B2 --prop value=12000 --json
officecli add budget.xlsx /Sheet1 --type cell --prop ref=A3 --prop value="API" --json
officecli add budget.xlsx /Sheet1 --type cell --prop ref=B3 --prop value=8000 --json
officecli add budget.xlsx /Sheet1 --type cell --prop ref=A4 --prop value="合計" --json
officecli add budget.xlsx /Sheet1 --type cell --prop ref=B4 --prop formula="=SUM(B2:B3)"

B4 に =SUM(B2:B3) を仕込んだ状態で get を実行すると、Excel を一度も開いていないにもかかわらず計算結果が返ってきた。

$ officecli get budget.xlsx /Sheet1/B4 --json

{
  "path": "/Sheet1/B4",
  "type": "cell",
  "text": "20000",
  "format": {
    "type": "Number",
    "formula": "SUM(B2:B3)",
    "cachedValue": "20000",
    "computedValue": "20000",
    "evaluated": true
  }
}

12000 + 8000 の合計 20000 が computedValue に正しく入り、evaluated: true も返る。この「書き込んだ瞬間に計算済みの値が返る」挙動は、AIエージェントが集計結果を次のステップの判断材料に使う際にそのまま利用できるという点で実務的に効いてくる。openpyxl の場合、数式は文字列として保存されるだけで実際の計算値を得るには別途 Excel か計算エンジンを介す必要があるのと対照的だ。

ハマりポイント: セルのパス指定

ここで最初につまずいた。ドキュメント階層をたどる感覚で /sheet[1]/cell[B4] のように角括弧でインデックス指定できるだろうと予想して実行したところ、次のエラーになった。

{
  "success": false,
  "error": {
    "error": "Invalid path index 'B4' in segment 'cell[B4]'. Expected a numeric index.",
    "code": "invalid_value"
  }
}

cell[B4] の B4 を数値インデックスとして解釈しようとして失敗している。officecli help xlsx cell でスキーマを確認すると、正しいパス表記が明記されていた。

Paths: /<sheetName>/<A1Ref>  /Sheet1/A1  /Sheet1/B2:C3

つまり /Sheet1/B4 のように、シート名の直後に Excel の A1参照をそのまま続ける記法が正解になる。角括弧インデックスは PowerPoint のスライド（/slide[1]）や Word の段落など、シーケンシャルな要素向けの記法で、セル参照には使わない。この違いは officecli help <format> <element> で要素ごとに個別に確認できるので、初回操作でパスエラーに当たったら該当要素のヘルプを見るのが早い。

query コマンドでも同様に、存在しないキーを指定すると使用可能なキー一覧を警告として返してくれる。

$ officecli query budget.xlsx "cell[ref=B4]" --json

{
  "warnings": [
    { "message": "Warning: unknown key 'ref'. Available: cachedValue, computedValue, evaluated, formula, text, type, value" }
  ]
}

エラーメッセージや警告が「次に何を試せばいいか」を返してくる設計になっており、AIエージェントが自己修正しながら操作を進める前提で作られていることが伺える。

Word・PowerPointも同じ操作体系で扱える

docx・pptx も xlsx と同じ動詞（create / add / get）で操作できる。段落を追加して HTML ビューで確認したところ、日本語テキストも問題なくレンダリングされた。

officecli create report.docx --json
officecli add report.docx / --type paragraph --prop text="週次レポート" --json
officecli add report.docx / --type paragraph --prop text="Claude Codeで自動生成しています。" --json
officecli view report.docx html

出力された HTML には追加した2つの段落がそのまま含まれていた。PowerPoint も同様にスライド追加が一発で通り、get で取得したノード情報にはタイトルのプレースホルダー座標（x: "66pt", width: "29.21cm"）まで含まれる。単位が pt と cm 混在で返ってくる点は、そのまま別ツールに渡す場合は変換が必要になる箇所として覚えておきたい。

AIエージェントへの組み込み

OfficeCLI 自体が officecli mcp サブコマンドで MCP サーバーとして起動できる。さらに officecli skills を実行すると、インストールされている Claude Code・Cursor・Windsurf・GitHub Copilot を自動検出し、各ツール向けのスキル定義ファイルを配置してくれる。CLI 単体としても、MCP 経由の統合としても使える二段構えになっている点は、単なる「Office 操作ライブラリ」ではなく最初からエージェント連携を前提に設計されていることの表れだ。

officecli install   # バイナリ + skills + MCP を検出した対象へ一括セットアップ

CI 環境や本記事のようなヘッドレスのクラウド実行環境でも、Office 本体なしでそのまま動く点は素直に便利だった。

まとめ

  • OfficeCLI は Office 未インストールでも docx/xlsx/pptx を操作できる単一バイナリの CLI（Apache 2.0・19.6k★）
  • Excel 数式は書き込み時点で自動評価され、computedValue としてそのまま取得できることを実機で確認した
  • セルのパス指定は /Sheet1/A1 の A1参照記法が正解で、角括弧インデックス記法は使えない（実機でエラーを確認済み）
  • officecli mcp / officecli skills により、CLI 単体でも MCP 経由でもエージェントに組み込める

著者視点の発見ポイント

実際に操作して意外だったのは、エラーメッセージや警告が単なる失敗通知ではなく「次に正しいキー・記法は何か」まで返してくる設計になっていた点だ。query で存在しないキーを指定した際に利用可能なキー一覧を warnings として返す挙動は、人間のデバッグよりも AIエージェントが自己修正のループを回すことを前提に設計されているように見えた。ドキュメント操作 CLI というと地味な印象を持ちがちだが、この「エージェント向けに失敗から学習させる」設計思想の部分が最も学びになった。

関連記事

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?