領収書をフォルダに入れて「記帳して」と言うだけで、マネーフォワード クラウド会計へ仕訳が登録される。そういう無償プラグインを公開しています。

ありがたいことに「入れてみました」というご連絡をいただくようになりました。同時に、「自動記帳がうまくいかない」と詰まる場所が、だいたい同じ5か所に集中していることも分かってきました。マネーフォワードのプラグイン設定そのものでつまずく方と、MFクラウドのAPI連携でエラーが出る方の、2種類です。

この記事は、その5か所を先回りしてお伝えするものです。すべて、私たち自身が実際に踏んだものです。設定を始める前にひと通り読んでおくと、余計な30分を使わずに済みます。

⚠️ 本プラグインは、株式会社マネーフォワードの公式製品ではありません。株式会社multi-solutionが独自に開発した非公式のツールです。「マネーフォワード クラウド会計」は株式会社マネーフォワードの登録商標です。ご質問・不具合の報告はGitHubのIssuesへお願いします。マネーフォワード社ではお答えできません。

---

先に：自分がどこで止まっているかを見分ける

つまずきは、どの段階で起きたかで原因がほぼ決まります。

止まった場所	該当するつまずき
初期設定（mf-setup）で事業者名が違う／進まない	①
記帳はできるが、領収書の添付だけ動かない	②
ブラウザで「許可」を押したら404が出た	③
昨日まで動いていたのに expired と出る	④
エラーは出ないが、記帳された件数が思ったより少ない	⑤

ご自身の症状に当たる番号へ進んでください。

---

① 別の事業者の帳簿につながっている

症状：初期設定で表示される事業者名が、記帳したい会社と違う。あるいは実行のたびに「事業者が一致しません」と止まる。

原因：マネーフォワードのコネクタは、あなたのアカウントで見える事業者のどれかにつながります。複数の事業者（自社と顧問先、法人と個人など）をお持ちの場合、意図しないほうにつながっていることがあります。

プラグインは実行のたびに「MCP接続先」「REST認証」「設定ファイル」の3つで事業者名が一致するかを突き合わせ、ひとつでも食い違えば停止します。これは不便なようでいて、意図的な設計です。帳簿の取り違えが、この仕組みで起こりうる最大の事故だからです。

解決：複数の事業者を扱う場合は、次の3つを事業者ごとに必ず分けてください。

1. 認証ファイル：oauth_init.py --creds ~/.mfc/credentials_◯◯.json のように別ファイルにする
2. 設定と処理済み台帳：事業者ごとのフォルダに .mf-cloud/（config.json・ledger.json）を持たせる
3. 作業フォルダとセッション：作業そのものを事業者ごとに分ける

ひとつのフォルダで2社分を処理しようとすると、台帳が混ざります。面倒でもフォルダから分けるのが結局いちばん早いです。

---

② 権限（スコープ）の設定にチェック漏れがある

症状：記帳は問題なくできるのに、領収書の添付だけが失敗する。あるいは原因の分かりにくいエラーが出る。

原因：証憑の自動添付（応用編）では、マネーフォワードのアプリポータルで12個の権限すべてにチェックを入れる必要があります。ここを1つ落としていると、落とした機能を使う場面まで来て初めてエラーになります。設定から日をまたいでいると、原因に結びつけるのが難しくなります。

とくに落としやすいのが、リストの最後にある「証憑の書き込み（voucher.write）」です。これが領収書添付の本体です。

解決：アプリポータルの登録内容を開き、12個そろっているか目視で確認してください。

• 事業者の読み取り（offices.read）
• 勘定科目の読み取り（accounts.read）
• 税区分の読み取り（taxes.read）
• 部門の読み取り（departments.read）
• 連携サービスの読み取り（connected_account.read）
• 仕訳の読み取り（journal.read）
• 仕訳の書き込み（journal.write）
• 取引先の読み取り（trade_partners.read）
• 取引先の書き込み（trade_partners.write）
• 取引の書き込み（transaction.write）
• レポートの読み取り（report.read）
• 証憑の書き込み（voucher.write） ← いちばん忘れられます

権限を追加したら、認可をやり直す必要があります（後述の reauth.py）。チェックを入れただけでは、すでに発行済みのトークンの権限は変わりません。

💡 そもそもAPIキーで済ませられないのかとよく聞かれます。マネーフォワードにはAPIキー認証もありますが、2026年8月時点でクラウド会計はAPIキーの対象外でした（発行画面で選べるのは「事業者情報」「クラウド連結会計」のみ・当社実測）。そのため、証憑添付が使う会計APIはブラウザでの認可（OAuth）が唯一の手段です。

---

③ 「許可」を押したら404 File not found

症状：ブラウザでマネーフォワードの「許可」を押した瞬間、真っ白な画面に「404 File not found」。ターミナルは待ち続けたまま終わらない。

原因：認可の受け取りにパソコンの中のポート8765という通り道を使うのですが、別のプログラムが先にそこを使っていると、許可の結果がそちらへ流れてしまいます。

私たちの場合は、以前立てたプレビュー用のサーバー（python -m http.server 8765）の消し忘れでした。実際に起きた事故です。厄介なのは、この状態で「許可」を押すと認可コードそのものが失われること。押し直しでは直りません。

解決：現在のスクリプトは、起動時にポートの占有を自動で検知して、占有しているプログラムを画面に表示します。表示されたものを終了してから、もう一度実行してください。

lsof -nP -iTCP:8765 -sTCP:LISTEN
kill <表示されたPID>

そのうえで oauth_init.py を再実行します。

💡 上のコマンドはMac用です。Windowsでは netstat -ano | findstr :8765 で使用中のプログラムを調べ、タスクマネージャーから終了してください。

なお認可の待ち時間は5分です。ブラウザ側で迷っているうちに時間切れになった場合は、落ち着いてもう一度実行すれば大丈夫です。

---

④ expired が何度も出る

症状：一度は成功したのに、しばらくすると「expired（認証切れ）」になる。認可をやり直すとまた動くが、また切れる。

原因：マネーフォワードのリフレッシュトークンは、更新のたびに新しいものへ入れ替わります（ローテーション）。そのため、次の場合に古いトークンが無効になります。

• 同じClient IDで認可をやり直した：以前のトークンはその時点で無効になります
• 複数のパソコン・複数の認証ファイルで同じClient IDを使っている：片方が更新すると、もう片方が無効になります

会社のパソコンと自宅のパソコンで同じ設定を使い回している方が、これに当たります。交互に使うたびに、相手側が切れるわけです。

解決：復旧は reauth.py です。

python3 <プラグインのパス>/scripts/reauth.py

保存済みのClient ID / Secretを再利用するので、ブラウザで「許可」を押すだけで戻ります。Client ID・Secretの再入力は不要です（oauth_init.py からやり直す必要はありません）。

そして根本的な対処は、環境ごとに別のアプリ（別のClient ID）を登録することです。パソコンが2台あるなら、アプリ登録も2つ。これで取り合いが起きなくなります。

---

⑤ エラーは出ないのに自動記帳の件数が少ない

症状：20枚入れたのに、確認表に出てきたのは12件だった。エラーメッセージは出ていない。

これは故障ではなく、そういう設計です。理由は3つあります。

(1) 証憑がないものは記帳しません 領収書が手元にないものは記帳せず、「証憑待ち」として一覧に残します。「仕訳はあるのに証憑が付いていない」状態を作らないためです。振込手数料や預金利息など、そもそも証憑が存在しないものは対象外として扱います。

(2) 同じ領収書は二度記帳できません 処理済みの管理を、ファイル名ではなくファイルの内容ハッシュ（SHA-256）で行っています。ファイル名を変えても、フォルダを移しても、同じ領収書は「記帳済み」と判定されます。「フォルダを移し忘れて二重計上」という事故を、運用ではなく仕組みで防ぐためです。

過去に入れたことのある領収書が混ざっていれば、その分は当然スキップされます。

(3) 1回の実行は30ファイルまでです 一度に大量に読ませると、読み取りの精度が落ちます。これは私たちが実際に失敗して決めた上限です。31枚目以降は次の実行に回してください。

確認方法：いま何が終わって何が残っているかは、次のコマンドで一覧できます。帳簿は変更しません。

/mf-cloud-import:mf-status

「証憑待ち」に並んでいれば (1)、「記帳済み」と出れば (2) です。

---

おまけ：「Operation not permitted」と出たとき

スクリプトの実行時に「Operation not permitted」や許可を求める確認が出ることがあります。これはClaude Codeの安全機能（サンドボックス）が、認証情報の置き場所である ~/.mfc/ へのアクセスを制限しているためです。表示された許可プロンプトを承認すれば進みます。毎回の承認が煩わしい場合は /sandbox コマンドで調整できます。

---

導入前のチェックリスト

設定を始める前に、これだけ確認しておくと詰まりにくくなります。

• 記帳したい事業者が1つに絞れている（複数扱うならフォルダから分ける）
• マネーフォワード公式のコネクタを、自分のアカウントで有効にした
• （証憑添付を使うなら）権限12個すべてにチェックした
• リダイレクトURIを1文字も変えずにコピペした
• ポート8765を使っている別のプログラムがない
• Client ID / Secret を控えた（Secretは一度しか表示されないことがあります）
• 最初は領収書1〜2枚だけで試す

最後の1行がいちばん大事です。いきなり全部入れないでください。 設定に思い違いがあったとき、影響を1〜2件に抑えられます。

---

まとめ

• 詰まる場所は5つに集中します。どの段階で止まったかで原因がほぼ決まります
• 事業者の取り違えは仕組みで止めています。止まったら設計どおりの動作です
• 権限12個はチェック漏れが後から効いてきます。とくに voucher.write
• 認可中の404はポート8765の取り合い。押し直しでは直らないので、占有を解いてやり直します
• expired の繰り返しは reauth.py で復旧。根本対処は環境ごとに別アプリを登録すること
• 件数が少ないのは仕様です。証憑なしは記帳せず、同じ領収書は内容ハッシュで二度目を弾きます

プラグインはこちらで公開しています。→ github.com/multi-solution/mf-cloud-import

はじめて導入される方は【基本編】マネーフォワードの記帳をAIに任せる方法から、証憑の自動添付まで進める方は【応用編】領収書を仕訳に自動添付する設定をご覧ください。

⚠️ 本プラグインの役割は「記録の作成を補助すること」に限られます。 税務相談・税務代理はいたしません。勘定科目・税区分の判定は参考情報です。最終的な確認と判断は、ご自身または顧問税理士が行ってください。電子帳簿保存法への適合は、ご自身の責任でご判断ください。 連携に用いるコネクタはベータ版のため、仕様が変更される可能性があります。

ここに書いていない症状で止まってしまった場合は、GitHubのIssuesへお知らせください。導入そのものをお手伝いすることもできます。設定の代行や、社内の経理フローに合わせた組み立てをご希望でしたら、お問い合わせからご相談ください。マネーフォワード クラウドの導入支援も行っています。