mfcli

Money Forward クラウド会計 API v3 を、LLM エージェントや自動化スクリプトから扱いやすくするための CLI です。

Money Forward は日本語UI・日本の会計実務を前提にしたサービスですが、エージェントが安全に使える形の CLI はまだ多くありません。mfcli は、OAuth 認証、JSON 出力、構造化エラー、ページング、token refresh を CLI 側で吸収し、エージェントが「会計データを読む」「集計する」「必要なら dry-run 後に書き込む」ための薄い実行レイヤーを提供します。

できること

• 標準出力は JSON。エラーも JSON。
• OAuth profile と token を ~/.config/mfcli 配下で管理。
• access token の自動更新と refresh token のローテーション追従。
• 勘定科目、補助科目、税区分、部門、取引先、仕訳、試算表、推移表などの取得。
• 仕訳・取引・証憑などの書き込み系コマンド。ただし --dry-run または --yes が必須。
• Money Forward 本体の /accounts 画面をブラウザで取得し、連携口座残高を読む補助機能。

会計統計や月次分析は、エージェントにとってかなり相性のよい領域です。APIから取ったマスタ、仕訳、レポートを JSON で渡せると、部門別推移、勘定科目別の増減、異常値確認、月次コメント作成などをかなり素直に自動化できます。

インストール

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

開発用:

pip install -e '.[dev]'
pytest

mf-accounts のブラウザ取得機能も使う場合:

pip install -e '.[browser]'

Playwright 管理の Chromium を使う場合:

python -m playwright install chromium

system Chrome/Chromium が入っている環境では自動検出します。その場合、Playwright 管理ブラウザの install は不要です。明示する場合は --chrome-path または MFCLI_MF_ACCOUNTS_CHROME_PATH を使います。

初回認証

Money Forward のアプリポータルで OAuth アプリを作成し、Redirect URI に次を登録します。

http://localhost:12345/callback

その後、CLIからログインします。

mfcli auth login

SSH先で使う場合でも、デフォルトではサーバー側ブラウザを開かず、認証URLを表示して code または Redirect URL の貼り付けを待ちます。

明示的に設定する場合:

mfcli auth configure \
  --client-id "$MFCLI_CLIENT_ID" \
  --client-secret "$MFCLI_CLIENT_SECRET" \
  --redirect-uri http://localhost:12345/callback \
  --client-auth-method client_secret_basic

mfcli auth login

読み取り専用 scope で認可したい場合:

mfcli auth login --read-only

よく使う読み取り

mfcli office get
mfcli term-settings list
mfcli accounts list --available true
mfcli sub-accounts list --account-id '<ACCOUNT_ID>'
mfcli taxes list --available true
mfcli departments list
mfcli partners list --available true
mfcli connected-accounts list

仕訳一覧は期間指定が必要です。

mfcli journals list --start-date 2026-04-01 --end-date 2026-04-30 --all-pages
mfcli journals get '<JOURNAL_ID>'

レポート:

mfcli reports trial-balance-bs --fiscal-year 2026
mfcli reports trial-balance-pl --start-date 2026-04-01 --end-date 2027-03-31
mfcli reports transition-bs --type monthly --fiscal-year 2026
mfcli reports transition-pl --type monthly --fiscal-year 2026

書き込み系

書き込み・削除系は、必ず --dry-run または --yes が必要です。

mfcli journals validate --from-json examples/journal.json
mfcli journals create --from-json examples/journal.json --dry-run
mfcli journals create --from-json examples/journal.json --yes

その他:

mfcli partners create --from-json examples/trade_partners.json --dry-run
mfcli transactions create --from-json examples/transactions.json --dry-run
mfcli vouchers create --journal-id '<JOURNAL_ID>' --file receipt.pdf --dry-run
mfcli vouchers delete --journal-id '<JOURNAL_ID>' --voucher-file-id '<FILE_ID>' --dry-run

mf-accounts

mf-accounts は、Money Forward クラウド会計 API では取得できない「Money Forward 本体の /accounts 画面」をブラウザで開き、連携口座・手入力資産の一覧をパースする補助機能です。

これは公式 Accounting API ではありません。読み取り専用で、ブラウザセッションと raw 取得結果はローカルの ~/.config/mfcli/moneyforward_accounts/ に保存されます。

初回ログイン:

mfcli mf-accounts login

初回ログインは MFA を含む手動操作が必要なので、画面を見て操作できるデスクトップ環境で実行します。サーバーでの --xvfb はログイン済み profile を使った更新用で、初回 MFA を完了する用途には向きません。

一覧取得。mf-accounts list は既定で headful/headed ブラウザを使います。Money Forward の /accounts は headless Chrome を拒否することがあるため、通常は --headless を付けません。

mfcli mf-accounts list --refresh
mfcli mf-accounts list --ttl 86400 --linked-only
mfcli mf-accounts list --name-contains サンプル株式会社

サーバー上では、headed ブラウザを仮想ディスプレイで動かす --xvfb を使います。

mfcli mf-accounts list --refresh --xvfb --linked-only

--headless は明示的に必要な場合だけ使うオプションです。Forbidden が返る場合は --headless を外すか、サーバーでは --xvfb を使ってください。

保存済みテキストをパースするだけなら、ブラウザは不要です。

mfcli mf-accounts parse raw-accounts.txt --linked-only

token refresh と cron

通常の API 呼び出しでは、access token が期限切れに近い場合に自動更新します。定期実行で token を保ちたい場合は keepalive-all を使います。

mfcli auth keepalive-all --min-access-seconds 1200

cron 例:

*/30 * * * * /path/to/mfcli auth keepalive-all --min-access-seconds 1200 --compact >> ~/.config/mfcli/keepalive.log 2>&1

更新履歴は次で確認できます。

mfcli auth refresh-audit --tail 20

設定ファイル

既定の保存先:

~/.config/mfcli/
  config.json
  profiles/default.json
  tokens/default.json
  refresh_audit.jsonl
  moneyforward_accounts/

環境変数:

MFCLI_CONFIG_DIR=/path/to/config
MFCLI_PROFILE=default
MFCLI_CLIENT_ID=...
MFCLI_CLIENT_SECRET=...
MFCLI_REDIRECT_URI=http://localhost:12345/callback
MFCLI_SCOPES='mfc/accounting/offices.read mfc/accounting/journal.read'

API メモ

• Accounting API base URL: https://api-accounting.moneyforward.com
• OAuth authorization server: https://api.biz.moneyforward.com
• Rate limit: 3 requests/sec per Client ID and office identifier
• Access token lifetime: 1 hour
• Refresh token lifetime: 540 days

公式資料:

• https://developers.api-accounting.moneyforward.com/
• https://developers.api-accounting.moneyforward.com/v3/openapi.yaml
• https://developers.api-accounting.moneyforward.com/rate_limiter
• https://developers.biz.moneyforward.com/docs/common/oauth/overview/
• https://developers.biz.moneyforward.com/docs/api/auth/