freee MCP セットアップ完全ガイド｜詰まりどころ8選
freee MCPで見積書発行が「一言」で済む世界を作る
Claude Code から freee（クラウド会計）を直接操作したい。見積書を作成し、受注時にそれを請求書へ変換し、最終的に取引・売掛・入金まで会計データに連動させる。これを「freeeで見積書を作って」の一言で済ませる仕組みを作るための入り口が、freee MCP の Claude Code プラグインです。
本記事は、私が今日（2026年5月3日）実際に手を動かして freee MCP プラグインをセットアップした記録です。不動産案件の見積書発行というリアルな業務起点で導入したため、手順の流れだけでなく「ここで詰まる」というポイントを実体験ベースで網羅しています。同じところで時間を溶かさないための完全ガイドとして使ってください。
結論から言うと、つまずきの9割は「Client Secret のコピペミス」と「アプリ権限スコープの設定漏れ」の2点に集約されます。これさえ先に潰しておけば、初回でも30分前後でゴールに到達できます。
MCP（Model Context Protocol）そのものをまだ整理しきれていない方は、先に以下の記事で全体像を掴んでおくと、本記事の内容が一気に立体的に見えます。
なぜ Claude Code に freee を繋ぐのか
freee はクラウド会計サービスとして広く使われていますが、ブラウザのUIを開いて見積書や請求書を一件ずつ作る作業は、地味に時間が溶けます。私自身、案件ごとに見積書のテンプレを呼び出し、品目を入れ、金額を入れ、税区分を確認し、PDFを書き出して送付するという一連のフローに毎回15〜20分は奪われていました。
そこで活きるのが Claude Code との連携です。Claude Code のチャット画面に「○○社向けにLP制作30万円・運用サポート月3万円で見積書を作って」と書けば、Claude Code が freee API を叩いて見積書を生成し、確認用のリンクまで返してくれる。受注したら「あの見積書を請求書に変換」の一言で、品目をそのまま引き継いだ請求書が即座に発行される。これが目指している世界です。
freee は2026年3月に公式 MCP サーバー（github.com/freee/freee-mcp）をリリースし、それと並行して Claude Code 用のプラグインも提供しています。公式が直接メンテしている MCP サーバーなので、API 仕様変更への追従も期待でき、業務利用に踏み切れる土台が整いました。
MCP方式とプラグイン方式、どちらを選ぶべきか
freee MCP には大きく2つの導入方式があります。内部的にはどちらも同じ公式 freee-mcp サーバーを使うのですが、管理体験が違います。
1. 標準 MCP 方式（.mcp.json で記述）
- Cursor / Claude Desktop / Claude Code など複数のMCPクライアントで互換
.mcp.jsonを自分で書く必要がある- Agent Skill（API リファレンス・使い方ガイド）は別途
npx skills addで追加が必須 - 従来の標準的な MCP セットアップ
2. Claude Code プラグイン方式
- Claude Code 専用。
/pluginコマンドで管理 - Agent Skill が同梱される
- アップデートも
/plugin経由で簡単 - 2025年から登場した新しい仕組み
結論として、ターミナル中心で Claude Code を使っている方はプラグイン方式が圧倒的に楽です。Skill が同梱されるため freee API のリファレンスが Claude Code に最初から見えており、「見積書のフィールド名は何？」のような質問にも自走で答えてくれます。本記事もプラグイン方式での導入を前提に進めます。
「そもそも MCP サーバーって何が出ていて、何が業務で使えるのか」を俯瞰したい方は、以下の記事も参考になります。
セットアップの全体像（5ステップ）
ゴールは「Claude Code を起動して freee の見積書や請求書を自然言語の指示で作れる状態」です。そのために通る5ステップは以下のとおりです。
- ステップ1: freee Developer でプライベートアプリを登録
- ステップ2: Claude Code プラグインをインストール
- ステップ3: OAuth 認証（Client ID / Secret の貼り付け＋ブラウザ認可）
- ステップ4: Agent Skill のインストール
- ステップ5: Claude Code 再起動＋動作確認
所要時間の目安は、freee Developer を初めて触る方で30〜45分、慣れていれば15分前後です。私の場合は invalid_grant エラーで3回ほど引っかかり、結果として40分ほどかかりました。逆に言えば、本記事のハマりどころを先に押さえれば初回でも30分以内に動かせるはずです。
ステップ1: freee Developer でプライベートアプリを登録
まずは freee 側でアプリ登録を行います。freee Developer にアクセスし、freee アカウントでログインします。事業所オーナーまたは管理者権限のあるアカウントで入ってください。
1-1. プライベートアプリ作成
「アプリ作成」から「プライベートアプリ」を選びます。プライベートアプリは自社内・自分専用で使うアプリで、freee の審査を通す必要がありません。社外公開しない用途であればこれで十分です。
- アプリ名: 任意。
claude-code-freeeのように用途がわかる名前を推奨 - アプリの種別: 「Webアプリケーション」を選択
1-2. コールバックURLを正確に入れる（最重要）
ここが最初のハマりどころです。コールバックURLは以下を完全一致で入力します。
http://127.0.0.1:54321/callback注意点はこの2つ。
localhostではなく127.0.0.1を使う。OAuth 仕様上、両者は同じものとして扱われない場合がある- 末尾の
/callbackまで含めて1文字違わず一致させる。スラッシュ漏れもエラーになる
OAuth コールバックは「設定値と実リクエストが完全一致」のときだけ通る仕組みなので、ここをミスすると認証フローの最終ステップで redirect_uri_mismatch エラーが出ます。
1-3. アプリ権限（スコープ）の設定が最重要ポイント
これが本記事で一番強調したい部分です。初期状態では権限スコープが何もチェックされていません。私はこの状態で OAuth 認証を進めて、invalid_grant エラーで一度目の壁にぶつかりました。
「アプリ権限」セクションで、以下を最低限チェックしてください。
- 「freee請求書」関連 — 見積書・請求書・納品書・領収書の操作に必須（★必須）
- 「会計」関連 — 取引・取引先・勘定科目・事業所などの操作（★推奨）
請求書系の操作だけが目的でも、事業所情報の取得や取引先一覧の参照が裏側で必要になるため、会計関連も合わせてオンにしておく方が後で詰まりません。「権限スコープ未チェック → invalid_grant」は freee MCP セットアップで最頻出のエラーと覚えておきましょう。
1-4. Client ID / Client Secret を控える
下書き保存すると、Client ID と Client Secret が発行されます。プライベートアプリは公開不要のため、下書き状態のままで動作します。
注意点は Client Secret は一度しか表示されないということ。再表示できないので、表示されたタイミングでパスワードマネージャや安全なメモに必ず控えておきます。後述しますが、ここを雑にコピペすると後段で必ず詰まります。
ステップ2: Claude Code プラグインをインストール
ターミナルで以下の2コマンドを順に実行します。
# 1. freee マーケットプレイスを Claude Code に追加
claude plugin marketplace add freee/freee-mcp
# 2. プラグインをインストール
claude plugin install freee-mcp@freee-mcp-marketplace1つ目のコマンドで freee 公式が運営するプラグインマーケットプレイスを Claude Code に登録し、2つ目のコマンドで実際に freee-mcp プラグインを取得します。インターネット環境にもよりますが、両コマンド合わせて20〜40秒で完了します。
インストール後、claude plugin list で freee-mcp が一覧に表示されていれば次に進みます。表示されていない場合は、マーケットプレイスの追加が成功しているか claude plugin marketplace list で確認してください。
ステップ3: OAuth認証（ここが本番）
続いて freee 側の Client ID / Client Secret と紐付けるための OAuth 認証を行います。
npx freee-mcp configure初回起動時はパッケージのダウンロードに15〜30秒かかります。プロンプトが順番に表示されるので、以下を入力していきます。
- Client ID: ステップ1で控えたもの（数字18桁前後）をそのまま貼り付け
- Client Secret: ステップ1で控えたもの（hex 128文字程度）を貼り付け
入力が終わると自動でブラウザが立ち上がり、freee の認可画面が表示されます。「許可」を押すと http://127.0.0.1:54321/callback にリダイレクトされ、ターミナル側で「認証成功」のメッセージが出ます。最後に対象の事業所を選んで完了です。
invalid_grant エラーが出たときの対処
私はここで3回ハマりました。invalid_grant はその名のとおり「認証情報が間違っている」というエラーで、原因は概ね2系統に絞られます。
- 1. アプリ権限スコープが空 — ステップ1-3 でスコープにチェックを入れ忘れている。Developer 画面に戻って必要スコープを追加して保存
- 2. Client Secret のコピペミス — Secret は 128文字程度の長い hex 文字列で、画面上で末尾が見切れたり、ドラッグ選択時に末尾だけ欠落することが本当によくある。必ずダブルクリック選択（語ベース選択）か、表示エリアを広げてから手動で全選択する
2回目以降の invalid_grant は、ほぼ確実にコピペミスです。私の場合は3回目に Secret を一度再生成し、生成直後に「コピー」ボタンで取得したものを使ったら一発で通りました。Client Secret は再生成しても元の Client ID は変わらないので、不安なら早めに再生成して取り直す方が早いです。
「📦 古い設定形式を検出しました」の警告は無視してよい
環境によっては freee-mcp 側から「古い設定形式を検出しました」という警告が出ることがあります。これは内部の設定ファイル形式の互換性に関するメッセージで、動作上の実害はありません。新しい形式への移行が促されているだけなので、放置して構いません。
ステップ4: Agent Skill のインストール
プラグイン本体には MCP サーバーとしての機能が含まれていますが、freee API のリファレンスや使い方ガイドは別の Agent Skill として配布されています。
npx skills add freee/freee-mcpこのコマンドで freee-api-skill がローカルにインストールされ、Claude Code から「freee の見積書フィールドって何があるの？」のような質問に対して、自走で API リファレンスを参照できるようになります。
Skill のインストール先について
少し戸惑うのが、npx skills add がインストールするディレクトリです。私の環境では Claude Code 固有の ~/.claude/skills/ ではなく、~/Desktop/projects/.agents/skills/freee-api-skill 配下に配置されました。
Claude Code は複数のスキルディスカバリパスを持っているため、動作するなら配置場所はそのままで問題ありません。実際、私の環境ではこの場所のままで Claude Code がスキルを認識しています。動作確認後にどうしても移動したい場合は、Claude Code のスキル探索パスを設定で確認してから判断してください。
ステップ5: Claude Code 再起動＋動作確認
ここまで完了したら、Claude Code を一度終了して再起動します。MCP サーバーやスキルの読み込みは起動時に行われるため、設定変更後の再起動は必須です。
claude起動後、まずは MCP サーバーが認識されているか確認します。
/mcp list出力に freee: connected のような行が含まれていれば接続成功です。続いて、シンプルな動作テストとして以下のような指示を送ります。
「現在の事業所情報を取得して」事業所名・所在地・適格請求書発行事業者番号などが返ってくれば、freee 側との連携は完了です。私の場合はここで一発成功し、所要時間は40分でした。
ハマりどころ総点検（実体験ベース）
ここまでの手順で踏みやすい落とし穴を、独立してまとめます。詰まったときはこのリストを上から確認してください。
1. コールバックURLを localhost で書いてしまう
必ず http://127.0.0.1:54321/callback。localhost 表記は OAuth では別物として扱われる場合があり、redirect_uri_mismatch の原因になります。
2. アプリ権限スコープを何もチェックしない
初回 invalid_grant の犯人ナンバーワン。「freee請求書」関連は最低限必須、「会計」関連も推奨でチェックします。
3. Client Secret のコピペで末尾が欠落する
2回目以降の invalid_grant はほぼこれ。約128文字の hex 文字列を扱うため、画面上で末尾が見切れることがよくあります。怪しいと思ったらSecret を再生成して取り直す方が早いです。
4. Webhook URL を OAuth と混同する
freee Developer 画面には Webhook URL の入力欄もありますが、OAuth 認証とは別物です。今回のセットアップでは触らなくて構いません。
5. 「📦 古い設定形式」警告で慌てる
freee-mcp 側の表示で実害なし。動作確認に進んで問題ありません。
6. Agent Skill のインストール先で混乱する
~/.claude/skills/ ではなく ~/Desktop/projects/.agents/skills/ 配下に入ることがあります。Claude Code が認識しているなら移動不要。動作確認を先に行ってから判断します。
7. プライベートアプリを「公開」しようとする
プライベートアプリは下書き保存のままで動作します。「公開」操作は社外配布用のアプリ向けで、自分専用の用途では不要です。
8. Claude Code の再起動を忘れて「動かない」と判断する
MCP サーバーやスキルの読み込みは起動時のみ。設定変更後は必ず Claude Code を一度終了して再起動します。
セットアップが終わると何ができるようになるか
ここまでで、Claude Code から freee を操作できる状態が完成します。具体的にできることを整理しておきます。
- 見積書の作成・取得 — 品目・金額・税区分・納期などをチャット指示で入力し、見積書を生成
- 請求書の作成・取得 — 既存の見積書から品目を引き継いで請求書化することも可能
- 取引先の登録・取得 — 新規クライアントの社名・住所・請求先情報を一括登録
- 事業所情報の取得 — 自社の登録情報、適格請求書発行事業者番号などを参照
- 取引・勘定科目の操作 — 仕訳・収支データの取得や登録
注意：PDF ダウンロードは API ではなく UI 側機能
1つ覚えておきたいのが、見積書や請求書の PDF ダウンロードは freee の UI 側機能であり、API では直接取得できないという点です。Claude Code 経由で見積書を作成した後、PDF が必要な場合は freee のブラウザ画面に戻ってダウンロードする必要があります。
とはいえ、見積書本体の作成と書類リンクの取得まで自動化できれば、月15〜20件の見積書を作るような事業者なら月間で数時間レベルの工数削減が見込めます。最後の PDF クリックだけは UI 側に残る、という前提で運用設計しておきましょう。
業務フローへの組み込み方
私の場合は、Claude Code のスラッシュコマンドや Skill として「見積書作成」を登録する想定で設計しています。たとえば以下のようなフローです。
ユーザー: /quote ○○社 LP制作30万円・運用サポート月3万円
Claude Code:
1. freee MCP 経由で取引先「○○社」を検索（なければ新規作成）
2. freee MCP 経由で見積書を作成
- 品目1: LP制作 / 数量1 / 単価300,000
- 品目2: 運用サポート / 数量1 / 単価30,000
3. 作成した見積書のURLをチャットに返す
4. PDF発行が必要な場合はブラウザを開く案内を出す受注したら同じく「あの見積書を請求書に変換して」の一言で請求書化、入金確認後は会計の仕訳まで自動連携、というのが最終形です。Claude Code を「見積書発行係」として常駐させるイメージで、これが回り始めると経理周りの体感速度がガラッと変わります。
MCP サーバー全体の活用イメージは、以下の記事で全体像を整理しています。
うまくいかないときのリセット手順
何度かやり直したくなることもあります。以下の順で戻すのが早いです。
# 1. OAuth 認証だけやり直したい
npx freee-mcp configure
# → Client ID / Secret を再入力 → ブラウザ認可
# 2. Client Secret を一新したい
# → freee Developer 画面で「Secret 再生成」
# → 新しい Secret で npx freee-mcp configure を再実行
# 3. プラグイン自体をクリーンに入れ直したい
claude plugin uninstall freee-mcp
claude plugin install freee-mcp@freee-mcp-marketplace特に invalid_grant エラーが繰り返し出る場合は、Secret 再生成 → configure 再実行がもっとも確実な復旧ルートです。アプリ権限スコープの追加・変更を行った場合も、設定保存後に configure を再実行しておくと反映が確実になります。
まとめ：詰まりどころを先に潰せば30分で動く
freee MCP の Claude Code プラグイン化により、会計まわりの自動化のハードルが大きく下がりました。手順そのものは5ステップで完結しますが、Client Secret のコピペミスとアプリ権限スコープの設定漏れという2大ハマりどころで時間を溶かしがちです。
本記事のポイントを再掲します。
- コールバックURLは
http://127.0.0.1:54321/callbackを完全一致で（localhostではなく127.0.0.1） - アプリ権限スコープは「freee請求書」必須・「会計」推奨で必ずチェック
- Client Secret は一度しか表示されないので即控える。怪しいときは再生成が早い
- プラグイン方式なら Agent Skill 同梱で API リファレンスもセットになる
- 動作確認は
/mcp listと「事業所情報を取得して」で十分
セットアップが終われば、見積書作成・請求書発行・取引先管理など、freee を起点にした業務フローを Claude Code に「指示する」だけで回せるようになります。月15〜20件の見積書発行を自動化できれば、本業に集中できる時間が確実に増える。会計まわりに毎月数時間取られている方ほど、最初の30分の投資対効果が大きい仕組みです。
御社の業務に合わせたClaude Code導入支援
「AIツールを導入したが、現場で使われない」を終わらせる。
業務課題のヒアリングから設計、ハンズオン実践、運用定着まで一貫して支援します。