エアレジCSV取得MCP

エアレジの帳票CSVを取得する道具です。Claude CodeやClaude DesktopなどのAIからMCPサーバーとして使えるほか、自分で打つコマンドとしても使えます。帳票・店舗・期間を指定してCSVを保存します。集計はしません。MacとWindowsで動きます。

取得できる帳票

どの帳票も、1店舗・1か月分を実際に取得し、画面の数字と合うことを確かめました（2026年11月）。定義は src/reports.mjs にあります。

帳票ごとの制限は次のとおりです。

• daily_sales と transaction_details は、1か月単位でしか取得できません。開始日は月の1日、終了日は月末（今月なら今日）にしてください。合わない期間を指定すると、start_download は取得を始めずに PERIOD_UNSUPPORTED を返します。今月分のファイルは、エアレジが期間を月末までとして名前を付けます（中身は今日までです）。

• transaction_details（会計明細）は、エアレジの制限で、前月1日から今日までの分しか取得できません。

• variation_sales と product_sales は、エアレジの画面では約3年分を1回で出せました。ツールは月ごとに分けて取得します。

Related MCP server: Browser MCP

はじめ方

使い方（docs/usage.md） に、AIごとの登録方法と、そのまま貼り付けて使えるプロンプトをまとめています。

必要なものは Node.js（22以上）、Git、Google Chrome です。Playwrightは、パソコンに入っているChromeを操作します。別のブラウザはダウンロードしません。

Claude Code、Codex CLI、Gemini CLI、Cursor のように、コマンドを実行できるAIなら、使い方の「AIに入れてもらう」 の文を貼り付けるだけで、入れて登録まで済ませてくれます。

手で入れる場合は、リポジトリのフォルダで依存パッケージを入れてから、AIに登録します。Claude Code の例は次のとおりです。

npm ci --ignore-scripts

claude mcp add --scope user airregi-csv -- node C:\path\to\airregi-csv-mcp\src\mcp.mjs

Claude Desktop、Cursor、VS Code、Codex CLI、Gemini CLI の登録方法は、使い方 にあります。

使うときは、AIに次のように頼みます。

airregi-csv で、全店舗の先月の日別売上（daily_sales）のCSVを取ってきてください。終わったら、店舗ごとの結果と保存先のフォルダを教えてください。

コマンドで使う

AIを通さずに、コマンドで取得することもできます。毎月決まった日に自動で取りたいときにも使えます。

node src/cli.mjs login

node src/cli.mjs download --report daily_sales --all-stores --last-month

オプションの一覧と、Windowsで毎月自動で取得する方法は、使い方の「コマンドで使う」 にあります。

MCPのツール

取得には時間がかかるため、start_download はすぐに job_id を返します。終わったかどうかは get_download で確かめます。

期間は月ごとに分けて取得し、店舗×月ごとに1ファイルを保存します。一度に取得できるのは120ファイルまでです。

ログイン

ログインは手動です。ログインが切れていると、ツールは LOGIN_REQUIRED を返します。そのときは open_login でChromeを開き、利用者がログインしてから、もう一度実行します。ログイン状態は保存先の auth.json に残り、次回から使われます。

自動でログインし直す機能は、まだありません。

結果の見方

get_download の results に、店舗×月ごとの結果が入ります。

取得できなかった店舗や期間を、売上ゼロとして扱わないでください。全体の status は completed、partial、failed、cancelled のどれかです。

保存先

環境変数 AIRREGI_APP_DATA で変えられます。CSVは保存先の downloads の下に、取得ごとのフォルダを作って保存します。start_download の output_dir に絶対パスを渡すと、そのフォルダに保存します。各フォルダの manifest.json に、取得の結果を残します。

安全のための動き

• 画面の店舗名、期間、ダウンロードしたファイル名が指定と一致しなければ、保存せずに止めます。

• エアレジ以外の画面へ移動したら止めます。

• 想定外のエラーの中身は、AIへの返事に出しません。中身を見たいときは、環境変数 AIRREGI_DEBUG=1 を付けると標準エラー出力に出ます。

• Macでは、保存したファイルを自分だけが読める権限にします。Windowsでは、ユーザーフォルダの権限で守ります。

不具合の報告

自由に使ってかまいません。うまく動かないところを見つけたら、Issue で教えてもらえると助かります。エアレジの画面が変わると取得が止まることがあるので、その連絡も歓迎です。

報告には、売上の数字、店舗名、CSVの中身、auth.json、パスワードを書かないでください。

注意

• このツールは、株式会社リクルートや Airレジ とは関係のない、個人が作ったものです。

• エアレジの利用規約に沿って、自分のアカウントで使ってください。

• 取得したデータは、使う前に画面の数字と合っているかを確かめてください。不具合で起きた損害については責任を負えません。

ライセンス

MIT

開発

npm test

テストはChromeを起動しません。エアレジへの実際の取得は、利用者のパソコンで確かめます。CIでは、MacとWindowsでテストを回します。

要件は docs/requirements.md、使い方は docs/usage.md にあります。