freeeへの証憑アップロードをClaude Codeで自動化した備忘録

たとえ単純なものであろうと、反復継続的な定型作業を手でこなすのは、誰しもあまり気が乗らないものです。弊所でもこれまではVBAやRPAでどうにか凌いできましたが、手に届くところへ舞い降りたAIエージェント。触ってみない手はありません。

とはいえ、先達が既に遥かなる高みでAIエージェントを駆使している姿を見かける一方で、弊所の関心は日常の不便や面倒を減らす程度のもの。

そこで、クライアントのDropboxフォルダを開いて、たまった領収書や請求書のPDF・写真を、freeeのファイルボックスへ手作業でアップロードする——。
本当に単純な作業ですが、これを練習台として、主に使っているClaude Codeで自動化してみました。
（都合により、クライアントに直接freeeへアップロードしてもらう運用にはせず、いったんDropboxを経由させています）

「AIエージェントに丸投げできないか」と思い立ったのはよいものの、結果的には、毎回手作業でアップロードした方がよほど効率がよかったかもしれません。それでも、興味の赴くまま大いに時間をかけてやってしまいました。

以下は、希望を投げた後はAI任せ、詰まるたびに試行錯誤してもらった経緯をまとめたものです。手はほとんど動かしていませんが、時間だけはしっかりかかりました。
Claude Codeの使用が前提ですが、「華麗にコマンドを打ちこなすなど夢のまた夢ながら、AIエージェントに何か一つ任せてみたい」というご同輩を想定して記載しています。
題材はfreeeへの証憑アップロードという狭い話で、後で触れるとおり、この手順そのものがどうしても必要になる場面は限られます。
ただ、Step5以降で生じたトラブルは、他の作業を自動化する場合でも同じように出てくる可能性がありますので、まとめだけでも参考になれば幸いです。

何を作るのか

• 監視対象: 特定のDropboxフォルダ直下にある新規のPDF・画像ファイル（JPG / JPEG / PNG。拡張子の大文字・小文字は問いません）
• アップロード先: freeeのファイルボックス
• 自動化のタイミング: 毎月1日・15日に自動実行
• おまけ: 実行結果をGmailに通知

これを、Claude Codeの「スケジュールタスク」機能と、freeeが公式配布している「freee-mcp」というプログラムの組み合わせで作成します。

MCP（Model Context Protocol）とは何かをAIに聞いたところ、「AIに外部のシステムやアプリと会話・連携させるための標準プラグイン（変換アダプター）」のようなものとのことでした。Claude Code専用の仕組みではなく、他のAIツールでも使われている業界共通の規格とのこと。当初はAPIとの区別もついていませんでしたが、触っているうちに何となくイメージがつくようになりましたので、このあたりの理解は後回しでも良さそうです。

準備するもの

• freeeの会計アカウント（事業所の管理者権限）
• Node.js（JavaScriptというプログラミング言語を動かすための土台となるソフト。公式サイトからインストーラーを入手できます。一度インストールすれば、それ以降は特に意識する必要はありません）
  これを入れると、この後の手順で使うnpxというコマンドが一緒に使えるようになります（あらかじめインストールしておかなくても、必要なプログラムをそのつどインターネットから取り寄せてその場で実行してくれるコマンドで、今回はfreee-mcpを動かすのに使います）
• ターミナル（コマンドを入力する画面のこと。Windowsなら「Windows PowerShell」で、最初から入っています）
• Claude Code
• （任意）Gmail連携済みのClaude Code環境

寄り道: なぜ「freee-mcp」を使うのか

本手順で自動化に成功する前に、一度遠回りをしています。
claude.aiのコネクタ設定には、あらかじめfreeeがリスト表示されていて、トグルをONにするだけで接続できてしまいます。

一見これで準備完了に見えましたが、今回の用途には使えませんでした。理由は2つあります。

1. ファイルアップロード専用のツールがない。 会計データの参照・更新用の汎用APIツールはあるのですが、ファイルボックスへのアップロードに使えるものがありませんでした。
2. 定期実行のタスク（クラウド実行）に紐付けられない。 その場のチャットでトグルをONにすれば freee は使えますが、クラウドで動く定期実行タスクに使わせようとすると、連携先として freee を指定できませんでした（タスクに渡せるコネクタの一覧に、freee が出てこなかった）。トグルのONは、あくまでその場のチャットから使うためのもの、という位置づけのようです。

結局、freeeが公式配布しているfreee-mcp（この後のStep4で導入するもの）に切り替えました。同じ「freee」でも、claude.aiのコネクタ一覧に出てくるものと、npx freee-mcp configureで導入するものは別物でした。 こちらにはfreee_file_uploadという専用ツールがあり、ローカルで動くスケジュールタスクからも問題なく呼び出せました（公式ドキュメントでも、ファイルアップロードとOAuth認証だけが「stdio のみ」＝ローカル起動時のみ、と書き分けられていました）。

その一方で、取引データの取得・作成・更新といったAPI操作は、クラウド側の接続でも一通りそろっています。 freeeでAIにやらせたいことの多くは、トグルをONにするだけで届く範囲です。弊所が遠回りをしたのは「ファイルボックスに放り込む」という一点だけがローカル導入を要求したからで、ローカル導入の用がなければ、これから説明するローカルセットアップ（Step1〜4）は不要です。

Step1: freeeで「プライベートアプリ」を作成する

freeeのAPIを使うには、まず自分専用の「アプリ」を作り、認証用のIDとパスワード（Client ID・Client Secret）を発行する必要があります。

1. freeeのアプリストア管理画面から「アプリ作成」に進む
2. 下表の項目を入力する
3. 利用規約に同意して「作成」をクリックする

項目	入力例
アプリ名	自由（例: ●●社ファイルボックスアップロード）
概要	自由（例: ファイルボックスへの自動アップロード用）
アプリタイプ	プライベートアプリ

今回はプライベートアプリを選択していますが、選択の分かれ目は「公開するかどうか」だけではありません。プライベートアプリは利用できる事業所が5つまでで、アプリストアでの公開もできません。6事業所以上で使う場合は、公開しなくてもパブリックアプリを選ぶ必要があります（この点はfreeeの公式ドキュメント「アプリについて」にも明記されています）。ただ、自社や数社のクライアントで使う範囲なら、プライベートアプリで足ります。公開しない「下書き」状態のままでも、自分のアカウントでの認証・利用には問題ありません。

なお、弊所ではクライアントごとに別々のアプリを作っています。1つのアプリで複数の事業所を扱うこともできますが、アプリを分けておけば、そのアプリが触れる範囲はその会社の中だけに収まります。何か想定外のことが起きても、影響が他に及ばないという安心感があります。

作成すると、その場で Client ID と Client Secret が発行されます。

⚠️ Client Secretはパスワードと同じ扱いです。 この後のStep4で、freee-mcpのセットアップ画面には入力しますが（そのために必要なものです）、それ以外の場所——AIとの会話やチャット、メールなどに貼り付けることは避けてください。

Step2: コールバックURLを設定する

「基本情報」タブの「コールバックURL」欄に、次の値を入力して保存します。

http://127.0.0.1:54321/callback

これは「freeeへのログイン許可が終わったあと、結果をどこに送り返すか」を指定する設定です。Step4で動かすプログラム（freee-mcp）がこのアドレスで結果を待ち受けるため、1文字も違わずに一致させる必要があります。

Step3: 権限を設定する

「権限設定」タブを開き、「ファイルボックス」の行の両方のチェックボックス（参照・更新）にチェックを入れて保存します。他の項目（振替伝票、取引先など）は今回は不要です。

「利用事業所情報」タブは、まだ何も表示されなくて正常です。Step4で実際にログイン認証すると、自動的に事業所が紐づきます。

Step4: ターミナルでfreee-mcpをセットアップする

ここまでで整えたのは、freee側の「このアプリからのアクセスを許可する」という受け入れ態勢だけで、これだけでは何も起こりません。ここからはfreeeの画面を離れ、実際にやり取りを行うfreee-mcpを自分のPCに導入し、Step1で発行したClient ID・Client Secretを渡して、両者を繋ぎます。

Windowsなら、スタートメニューから「Windows PowerShell」を開きます。スタートメニューに「ターミナル」というアプリがあれば、そちらでも構いません。VSCodeをお使いなら、そちらでも大丈夫です。

以下のコマンドを入力してEnterキーを押します。

npx freee-mcp configure

y と答えると、対話式のセットアップウィザードが始まります。

? FREEE_CLIENT_ID: » (ここにStep1のClient IDを入力)
? FREEE_CLIENT_SECRET: » (ここにClient Secretを入力。画面には***で隠れます)
? コールバックポート (コールバックURL: http://127.0.0.1:<port>/callback): » 54321

ポート番号は初期値（54321）のままEnterでOKです。

すべて入力すると、既定のブラウザが自動的に開き、freeeのログイン許可画面が表示されます。これがOAuth認証と呼ばれる手続きです（ユーザーがパスワードを教えることなく、外部アプリにデータへのアクセス権限を安全に許可する仕組み）。

1. ログインし、アプリとの連携内容（ファイルボックスの参照・追加/変更/削除など）を確認
2. アクセスを許可する事業所にチェック
   （初期状態では全事業所にチェックが入っているはずです。実際に操作する事業所は、この後ターミナル側で1つ選びます）
3. 「許可する」をクリック

ブラウザでの許可が完了すると、ターミナルの表示が自動で進み、対象の事業所を選ぶよう聞かれます。

? 操作対象の事業所を選択してください（↑↓で選択、Enterで確定）: » ○○株式会社 (ID: 1234567)

該当する事業所を選んでEnterを押すと、認証情報が ~/.config/freee-mcp/ 配下（~ は自分のユーザーフォルダを指す記号で、Windowsなら C:\Users\（ユーザー名））に保存され、続けてClaude Codeへの登録を聞かれます。

? Claude Code に freee-mcp を追加しますか？ ... yes
? Claude Desktop に freee-mcp を追加しますか？ (Y/n)

1つ目は、今回の自動化をClaude Codeで動かすので yes です。

ここで一つ注意があります。Claude Codeは、設定を「フォルダごと」に覚えることがあります。この「Claude Code に追加しますか？ → yes」で入れた freee との連携も、そのとき開いていたフォルダ専用の設定として保存されることがあります。

そうなると困るのが、後で作る自動実行（スケジュールタスク）です。自動実行は別のフォルダを起点に動くため、そのフォルダには freee の設定が無く、「freee とはつながっているはずなのに、機能が呼び出せない」という状態になります。弊所も実際に一度これで足止めを食いました。

防ぐには、freee との連携を「特定のフォルダ専用」ではなく「どのフォルダからでも使える」設定として登録し直しておきます。セットアップがひととおり終わったら、ターミナルでもう一度だけ次を実行します。

claude mcp add --scope user freee -- npx freee-mcp

末尾の --scope user が「どのフォルダからでも使えるようにする」という指定です。これを付けておけば、自動実行のフォルダからも freee が見えます。

（configure の途中で登録方法の案内が出た場合は、その指示を優先してください。）

2つ目は、「Claude Desktopのチャット側でもfreeeを使えるようにするか」を聞いています。Claude CodeとDesktopのチャットは、設定ファイルが別々だからです。今回の自動化はClaude Code側で動くので、n としました。チャットからもfreeeを操作したい方は y にしてください（後から追加もできます）。

最後に「セットアップ完了！」と表示されれば成功です。設定を反映するため、Claude Codeを一度再起動してください。

⚠️ 無人でスケジュール実行するなら、ここでもう一手間かけておきます。

素の npx freee-mcp configure のままだと、起動のたびに新しい版を確認しに行き、キャッシュが失われていると「インストールしてよいか」の確認で止まります。対話セッションなら答えられますが、無人実行では答えられず、Claude Codeは既定でMCPサーバーの起動を30秒で打ち切るため、そのまま自動実行が失敗します（弊所もテスト中に一度これで止まりました。freee側に問題はありませんでした）。

対処として、~/.claude.json の freee-mcp の起動コマンドに次を指定し、確認待ちを止め・キャッシュ優先・版を固定します。

"args": ["-y", "--prefer-offline", "freee-mcp@<セットアップ時点の最新版>"]

あわせて ~/.claude/settings.json に次を足し、起動の待ち時間に余裕を持たせます（freee-mcp専用ではなく、全MCPサーバー共通の設定です）。

{ "env": { "MCP_TIMEOUT": "60000" } }

これで完全に解決したとは断言できませんが、その後、手動再実行と通常のセッション起動では接続は安定しています。

なお、ここまでの設定は「freee-mcpというプログラムが起動するかどうか」の話で、「freeeにログインした状態が続くかどうか」とは別の話です。動かなくなったとき、どちらが原因かで対処が変わります。

ログイン状態の方は、普段は自動で更新されるので放っておけます。ただし3ヶ月ほど経つと（あるいはfreee側の都合で）、その大元にあたる許可が切れます。そうなったらStep4の npx freee-mcp configure をもう一度実行し、ブラウザで許可を取り直すだけです（技術的には、短時間で切れる「アクセストークン」は自動で更新され、その大元の「リフレッシュトークン」が切れたときだけ再認証が要る、という仕組みのようです）。ここだけは、どんな設定をしても自動化できない唯一の手作業です。

Step5: Claude Codeにスケジュールタスクを作らせる

再起動後、新しいセッションでClaude Codeに次のように依頼します（実際に弊所が使った指示をベースにしています）。

対象フォルダ内の新規PDF・画像ファイルを、毎月1日と15日にfreeeのファイルボックスへ自動アップロードするスケジュールタスクを作って。アップロード済みのファイルは、ファイル名の先頭に区別できる印を付けてほしい。

Claude Codeは、この指示を SKILL.md という設定ファイルの形で保存し、cron（あらかじめ決めた時刻に処理を自動で実行する仕組み）のような形で定期実行してくれます。弊所が行った設定のポイントを挙げると:

• サブフォルダは対象外にする（クライアントのフォルダ直下だけを見る）
• アップロード済みファイルには up済 20260101_ のような日付入りの印を付け、二重アップロードを防ぐ
  （アップロード自体は成功したのに直後のリネームだけ失敗すると、次回また同じファイルが対象になってしまいます。リネームの成否も含めて「完了」とみなす設計にしておくと安心です）
• アップロードに失敗したファイルはリネームしない（次回また対象になるように）

設定ができたので、実際に動かしてみます。
実行のたびに「このコマンドを実行してよいか」と聞かれるのは煩わしいので、つい「常に許可」を選びがちになり、ここでひとつ、トラブルが生じました。

🪤 トラブル①: Claude Codeの権限プロンプトで「常に許可」を押すと、その時に実行したコマンド文字列が、そのままの形で許可ルールとして保存されます。
つまり、保存されるルールは mv "●●コンビニ領収書.pdf" "up済 20260822_●●コンビニ領収書.pdf"
（mv はファイル名を変更するコマンドで、「元の名前」「新しい名前」の順に並べます）のように、ファイル名も日付も丸ごと含んだものになります。翌月にファイル名が変われば一致せず、また同じ許可確認が出てしまいます。これでは放っておける自動化にはなりません。
AIの理由解説によると、これは安全性を優先した既定の挙動とのことでした（ワイルドカードで緩く許可すると、意図しない別のコマンドまで通してしまう恐れがあるため）。

対処: .claude/settings.local.json の permissions.allow に Bash(mv:*) のような（mv で始まるコマンドなら何でも通す）ワイルドカードルールを入れるように指示を出しました。
なお、freeeアップロードやGmail送信などのMCPツールは、ツール名そのもので許可できるため、この（ファイル名や日付で変わってしまう）問題は起きません。
スケジュールタスクを「完全放置」にするには、初回実行で出そうなコマンドを洗い出し、パターンで許可しておくのがコツのようです。ただし、これで足りるとは限らないと後で知ることになります（Step7）。

Step6（おまけ）: 実行結果をGmailに通知する

「毎月ちゃんと動いているか、いちいちDropboxを覗かないと分からない」という状況は避けたく、実行結果をメールで受け取れるようにしました。Gmail連携済みのClaude Code環境であれば、次のように依頼するだけです。

実行結果を自分のGmail宛にメールで送って。0件の月も含めて毎回送って。

ここでもう一つのトラブルです。

🪤 トラブル②: 弊所のメールアドレス宛にAPI経由で送信すると、受信トレイに配達されず、既読状態のまま『すべてのメール』にだけ入ってしまいました。
これでは通知として気づきづらいので、フィルタ設定を疑って延々と確認しましたが原因はフィルタではなく、AIによると自分宛送信特有のGmail側の挙動のようでした。

対処: AIが示した方法はシンプルで、メール送信の直後に、そのメールへ INBOX と UNREAD のラベルを明示的に付け直すことでした。Claude CodeのGmail連携ツールであれば、送信結果で得られる messageId に対してラベル更新を1回呼ぶだけで解決しました。この一手間をスケジュールタスクの手順にも組み込むようにしました。
なお、弊所は受信トレイをタスク管理に使っているためGmailを選びましたが、Slackなど別の通知手段であれば、この問題自体が起きません。

Step7: 「動く」と「放っておいても動く」の間 ― 権限設定の落とし穴

Step6までで一通り仕上がった——と思っていましたが、何度目かの再テスト時に、また止まりました。「手元で動く」と「放っておいても動く」の間には、思っていたより距離がありました。原因はコマンドの中身ではなく、Claude Codeが実行前に出す権限確認そのものです。

トラブルは一度ではなく、対処するたびに別の形で出てきました。コマンドやツールを1つずつ許可リストに足していく方式では追いつかず、最終的に、「種類」単位でまとめて許可する形に行き着きました。

最終形: 「種類」でまとめて許可する
対象フォルダの .claude/settings.local.json を、次の形にしました。

{
  "permissions": {
    "allow": [
      "mcp__freee-mcp",
      "mcp__（Gmail連携のサーバー名）",
      "mcp__scheduled-tasks",
      "Bash",
      "Read",
      "Glob",
      "Grep"
    ],
    "additionalDirectories": [
      "C:/Users/（ユーザー名）/Dropbox/（対象フォルダ）"
    ]
  }
}

mcp__scheduled-tasks は、スケジュールタスクの仕組みそのものが使うMCPサーバーです。これも同じ要領（サーバー名だけ）で許可します。

ポイントは2つです。
・MCPサーバー名を、ツール名を付けずに書く → そのサーバーの全ツールが許可されます。
・ツール名だけを書く（Bash、Read、Glob など） → そのツールの全操作が許可されます。

ツール名	意味
Bash	ターミナルでコマンドを実行する機能
Read	ファイルの中身を読む機能
Glob	ファイルを名前で検索する機能
Grep	ファイルの中身（テキスト）から探す機能

この形にしたところ、freeeへのアップロードからGmail送信まで、確認ゼロで通しで完走しました。

⚠️ ただし、これは安全機構を緩める設定です。 Bash を丸ごと許可するということは、そのフォルダで動くセッションは、どんなコマンドでも確認なしで実行できるということです。これを許容できたのは、次の3つが揃っているからです。

1. 設定を書いたのは .claude/settings.local.json で、そのフォルダ配下でだけ有効（ユーザー全体の設定ではない）
2. そのフォルダはクライアントとの証憑受け渡し用で、Claude Code を動かすのはこのルーティンだけ（他の作業では使っていない）
3. SKILL.md 側でも「コマンドを連結しない」等で、AIが使うコマンドの形を狭めてある

ユーザーレベルの設定ファイル（~/.claude/settings.json）に同じ権限設定を書くと、全プロジェクトに適用されてしまいます。権限設定はそこに書かないでください。

― 以下は、この形に行き着くまでのトラブルの履歴です ―

トラブルの履歴（③〜⑤）

記号・コマンド	意味	最終ルールでの扱い
mv	ファイル名を変更する	使う（リネーム）
cd	作業する場所（フォルダ）を移動する	使わない（実行ルールで禁止）
ls	フォルダの中身を一覧表示する	走査で使うことがある
cat	ファイルの中身を表示する	使わない（手順になく、③でAIが足したもの）
&&	「前が成功したら、続けて次を実行する」	使わない（実行ルールで禁止）
|	「前の結果を、次のコマンドに渡す」	使わない（実行ルールで禁止）
Glob	ファイルを名前で探す機能 （下記で「ファイル検索ツール」と呼ぶのはこれ）	走査で ls の代わりに使うことがある

🪤 トラブル③: チェーンでつないだコマンドが止まりました。実行されたのは、こういう1行です（読みやすさのため簡略化しています）。

cd "対象フォルダ" && mv "A.jpg" "up済 20260901_A.jpg" && mv "B.png" "up済 20260901_B.png" && ls -la | cat

SKILL.md が求めているのは mv でのリネームだけです。cd も ls -la | cat も、AIが「先に移動しておこう」「結果を確認しておこう」と先回りして足したものでした。Claude Codeはこの1行を、&& や | で区切られた部品ごとに「許可済みか」を判定します。mv・ls は許可済みでしたが、cd・cat が許可リストに無く、タスクに必要ないコマンドが原因でチェーン全体が止まりました。

対処（仮）: cd・cat を許可リストに足し、SKILL.md でも「ls ではなくファイル検索ツールを使う」よう指示を変えました。

🪤 トラブル④: ls をやめたら、今度は「作業できる場所の外」と止められました。

Path is outside allowed working directories

「ls ではなくファイル検索ツールを使う」よう SKILL.md を書き換えた直後、その走査ステップで出ました。走査先は Claude Code を起動したフォルダそのもので、理屈のうえでは範囲の外になりようがない場所です。

対処: エラー文の "allowed" につられて permissions.allow に足したくなりますが、ここで止まっているのは操作の可否ではなく「場所」の判定なので、allow では直りません。その場で効いたのは SKILL.md を ls に戻すことでした（permissions.additionalDirectories にもこのフォルダを登録したので、どちらが効いたのかは切り分けられていません）。なぜ「範囲の外」と判定されたのかの機序は、いまも分かっていません（Dropbox のパス解決あたりが疑わしい、というところで止まっています）。

寄り道: 「全部の確認を無効化する」設定（.claude/settings.local.json の "defaultMode": "bypassPermissions"）も試しましたが、確認は出続けました（当時のWindowsでの観測。Claude Code は更新が速いので今は違うかもしれません）。

🪤 トラブル⑤: 今度はコマンドではなく、MCPツールで止まりました。freeeのツールを freee_set_current_company / freee_get_current_company / freee_file_upload の3つだけ個別に登録していたため、認証状態を確認する freee_auth_status が呼ばれた瞬間に止まりました。

ここで分かった根本原因
③と⑤は、どちらも「登録の粒度が細かすぎる」という同じ話でした。AIは実行のたびに、使うコマンドやツールの書き方をその場で決めるようです。SKILL.md には「フォルダを走査する」「リネームする」としか書いていないので、ある月は mv 単独、別の月は cd && mv && ls | cat、また別の月は検索ツール、と形が変わります。許可リストは「その形を事前に言い当てて登録しておく」仕組みなので、出たものを後から1つずつ足す方式では原理的に追いつきません。だから、書き方の違いを問わない「種類」単位の許可が要る、という結論です。

④だけは種類が違い、許可リストではなく作業ディレクトリの境界チェックに引っかかったものでした。ただし「個別対処していたら次は別の場所から出てきた」という点では同じで、実際この進め方で3回続けて外しました。「種類」単位にしてからは、SKILL.md が ls と検索ツールのどちらを使っても止まらなくなり、④の違いも問題になりません。

まとめ

参考までに、Step1〜7を通じた総時間は合計6時間ほどでした。結果的に時間がかかったのは、「アップロード機能そのもの」ではなく、次の3点の理解と対処でした。

1. freee連携は、接続方式（リモート/ローカル）によって使える機能が変わる（ファイルアップロードはローカル接続限定）
   →先達の情報発信を見ていたものの、自ら触るまで理解できていなかった
2. つい押しがちなClaude Codeの権限「常に許可」は、実行したコマンドがそのまま許可ルールになるため、ファイル名や日付を含む場合は次回から効かなくなる（ワイルドカードのルールで対処する）
3. そのワイルドカードのルールでも足りないことがある。コマンドやツールの形は実行のたびに変わるので、個別に登録していては追いつかず、ツールの種類単位・MCPサーバー単位でまとめて許可する必要があった。あわせて、これとは別の種類の制限として、作業してよいフォルダの範囲（additionalDirectories）も明示しておかないと、「放っておいても動く」状態にはならなかった（Step7）

なかでもStep7の「放っておいても動く」状態に持っていく権限まわりの調整が大半でした。freeeの画面設定やターミナルのウィザード自体は、案内どおりに進めるだけで済みます。
結果として、証憑アップロードという小さなタスクに、想定よりずっと時間がかかってしまいました。先達の発信に助けられてばかりでしたので、同じトラブルに見舞われた方の時短に多少でもなれば幸いです。