freee MCPサーバーの認証方法は？

OAuth 2.0 Authorization Code + PKCE方式を採用しています。freee Developer Portalでアプリを登録し、access_token（有効期限24時間）とrefresh_token（有効期限90日）を取得します。npx @freee/mcp-serverを使用するとOAuth認証フロー全体が自動化されるため、最も簡単な実装方法です。

freee APIでcompany_idが必要な理由は？

freeeは1つのアカウントで複数の会社・事業所を管理できます。そのため、ほぼ全てのAPIエンドポイントでどの会社のデータを操作するかを指定するcompany_idが必須です。最初に必ずGET /api/1/companiesを呼び出してcompany_idを取得してから、他のAPIを呼び出す必要があります。

freee APIのレート制限は？

アクセストークンごとに1時間あたり3,600リクエストが上限です。ウォレット・取引エンドポイントは5分あたり300リクエストの追加制限があります。制限超過時はHTTP 429が返り、レート制限ヘッダーで残余リクエスト数を確認できます。

Service Deep-Dive 2026-04-23 12 min read

freee MCPサーバー完全攻略 — OAuth PKCE認証・5ドメイン統合・エージェント開発の落とし穴2026

freeeは日本の中小企業向けクラウド会計・HR・給与の圧倒的シェアを持つSaaSだ。KanseiLink AEO評価ではAAAグレード・成功率90%・平均レイテンシ216msを記録している。公式MCPサーバー（npx @freee/mcp-server）は会計・HR・給与・経費・請求書の5ドメインを1本で統合する強力な実装だが、OAuth 2.0 PKCEとcompany_id必須という2つの設計がエージェント開発者の最初の壁になる。本記事では2026年4月時点のKanseiLink実測データをもとに、freeeのAEO評価根拠・5ドメイン統合の設計・認証完全ガイド・落とし穴・MoneyForward Cloudとの比較まで徹底解剖する。

🚨 アクティブ警告（2026-04-23時点）

KanseiLink監視データによると、freee MCPサーバーのauth_expired（OAuth 2.0トークン失効）エラーが過去24時間でベースラインの4倍に急増しています。freeeを使用中のエージェントは、トークンリフレッシュロジックの実装状況を今すぐ確認してください。詳細は「落とし穴①」のセクションを参照。

1. freee AEO評価 — AAAグレードの根拠

AAA

freee MCP — KanseiLink AEO格付け 成功率: 90% (212件のレポート) | 平均レイテンシ: 216ms | 公式MCP: ✅
最終更新: 2026-04-13 | 最新変更: v2 /invoices/bulk (2026-04-05)

評価軸	freeeの実績	評価
公式MCPサーバー	freee株式会社公式（@freee/mcp-server）、npxで即起動可能。Remote MCP（2026-03-27追加）でクラウド接続にも対応	✅ 最高水準
ドメインカバレッジ	会計・HR・給与・経費精算・請求書の5ドメインを1つのMCPサーバーで統合	✅ 業界最広
API成熟度	REST API v1/v2、ページネーション・バルク操作・Webhook完備。2026年4月にBulk Invoices API(v2)追加	✅ 高成熟
成功率	90%（212件のエージェントレポートより）。平均レイテンシ216ms（直近5件は250〜2,500ms）	✅ 良好
ドキュメント品質	developer.freee.co.jp に詳細な日本語APIリファレンスを整備。エンドポイント別のサンプルコード付き	✅ 良好

ただし、trust_scoreは0.9（満点1.0）で、同カテゴリのMoneyForward Cloud（0.93）をわずかに下回る。この差は主にOAuth 2.0 PKCEの24時間トークン失効問題と、一部エンドポイントでの散発的なapi_error（15件）に起因している。

2. 5ドメイン統合の全体像

freee MCPサーバーの最大の特徴は、1つのサーバーで企業の基幹業務5領域をカバーする点だ。エージェントは単一のMCP接続で、会計・人事・給与・経費・請求書をまたいで業務を自動化できる。

📊

会計（Accounting）

仕訳・取引・勘定科目・試算表・決算書。確定申告・帳簿管理の自動化に対応。

主要: /deals, /journals, /account_items

👥

HR（人事）

従業員管理・入退社・勤怠データ連携。SmartHRとの違いはfreeeエコシステム内での完結性。

主要: /hr/employees, /hr/work_records

💴

給与（Payroll）

給与計算・給与明細・賞与処理。会計ドメインと連動して給与仕訳を自動生成。

主要: /salaries/work_records, /payroll_periods

🧾

経費精算（Expenses）

経費申請・承認フロー・領収書管理。OCR連携でレシートから自動仕訳が可能。

主要: /expense_applications

📄

請求書（Invoicing）

請求書作成・送付・入金管理。2026年4月にBulk Invoices API (v2)が追加され、一括発行が大幅に高速化した。インボイス制度対応（適格請求書番号の自動付与）済み。

主要: /invoices, /invoices/bulk (v2 NEW), /partners

💡 設計のポイント：ドメインをまたぐ業務自動化

freeeの強みは5ドメインが同一のcompany_idと認証トークンで操作できること。例えば「経費申請承認→仕訳自動生成→給与計算連動」を単一のエージェントフローで実現できる。kintoneのようにアプリごとにAPIトークンを発行する必要がなく、OAuth 2.0で一括認証できる点は大規模自動化に有利。

3. OAuth 2.0 PKCE認証 — ステップバイステップガイド

freeeはAPIキー認証を採用していない。すべてのAPIアクセスはOAuth 2.0 Authorization Code + PKCE（Proof Key for Code Exchange）フローを通じて行う必要がある。これがfreeeをkintoneやSlackと比べて「最初の壁が高い」と感じさせる主因だ。

1

Developer Portalでアプリを登録

app.secure.freee.co.jp/developers にアクセスし、新規アプリを作成。redirect_uri（ローカル開発なら http://localhost:3000/callback でも可）を設定し、client_idを取得する。
2

PKCE用のcode_verifierとcode_challengeを生成

セキュリティ上、PKCEには128文字のランダム文字列（code_verifier）とそのSHA-256ハッシュ（code_challenge）が必要。npx @freee/mcp-serverを使えばこの手順を自動化できる。
3

認証URLにリダイレクト

ユーザーを https://accounts.secure.freee.co.jp/public_api/authorize?client_id=...&redirect_uri=...&response_type=code&code_challenge=...&code_challenge_method=S256&scope=read+write にリダイレクトし、freeeアカウントでの認証を求める。
4

authorization_codeをaccess_tokenと交換

freeeから返ってきたcodeを使い、POST https://accounts.secure.freee.co.jp/public_api/token でaccess_token（有効期限24時間）とrefresh_token（有効期限90日）を取得する。
5

GET /api/1/companiesでcompany_idを取得

access_tokenを取得したら、最初に必ずこの呼び出しを行い、company_idを取得する。これを省略するとほぼ全てのAPIで「company_idが必要」エラーになる。

      最小実装例 — company_id取得からDeal一覧まで
// Step 5: company_id取得（必須・最初の呼び出し）
const companiesRes = await fetch(
  'https://api.freee.co.jp/api/1/companies',
  { headers: { 'Authorization': `Bearer ${accessToken}` } }
);
const { companies } = await companiesRes.json();
const companyId = companies[0].id; // 例: 123

// Step 6: 取引一覧を取得（company_idが必須）
const dealsRes = await fetch(
  `https://api.freee.co.jp/api/1/deals?company_id=${companyId}&type=income&limit=100`,
  { headers: { 'Authorization': `Bearer ${accessToken}` } }
);
const { deals, meta } = await dealsRes.json();
// deals: 取引の配列, meta.total_count: 総件数

// Step 7: 一括請求書発行（2026-04-05追加のBulk API v2）
const bulkRes = await fetch(
  'https://api.freee.co.jp/api/2/invoices/bulk',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ company_id: companyId, invoices: [...] })
  }
);
    

4. エージェント開発者が必ずハマる4つの落とし穴

⚠️ 落とし穴①：access_token は24時間で失効する（現在急増中）

freeeのaccess_tokenは24時間で失効する。2026-04-23時点でauth_expiredエラーがKanseiLink監視上でベースラインの4倍に急増している。原因調査中だが、トークンリフレッシュのタイミングずれが疑われる。対策：refresh_token（有効期限90日）を使って自動リフレッシュするロジックを必ず実装すること。POST /public_api/token?grant_type=refresh_token&refresh_token={token}&client_id={id} でトークンを更新できる。

      トークン自動リフレッシュ — 必須実装パターン
async function getValidToken(stored) {
  const expiresAt = stored.issuedAt + 23 * 60 * 60 * 1000; // 23時間（余裕を持つ）
  if (Date.now() < expiresAt) return stored.accessToken;

  // リフレッシュが必要
  const res = await fetch(
    'https://accounts.secure.freee.co.jp/public_api/token',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: stored.refreshToken,
        client_id: process.env.FREEE_CLIENT_ID,
      })
    }
  );
  const data = await res.json();
  return data.access_token; // 新しいaccess_tokenを保存すること
}
    

⚠️ 落とし穴②：company_idなしで全てのAPIが失敗する

freeeは1アカウントで複数会社を管理できるため、ほぼ全てのエンドポイントでcompany_idパラメータが必須だ。エージェントが最初にGET /api/1/companiesを呼び出さずに他のAPIを実行すると、400エラーが返る。company_idはセッション内でキャッシュし、以降のAPIコールに自動付与する設計を推奨する。

⚠️ 落とし穴③：金額フィールドはJPY整数（小数点なし）

freee APIの全ての金額フィールドは日本円の整数で表される。1000 = ¥1,000。外貨取引の場合も最終的にJPY換算の整数で格納される。LLMが小数（例: 1000.50）を生成した場合は必ず整数に変換してから送信すること。また、消費税額も整数として別フィールドに格納されている。

⚠️ 落とし穴④：大量データ取得でタイムアウトする

日付範囲を指定せずにGET /dealsを実行すると、数千件の取引を返そうとして800ms超のレイテンシ（実測）が発生しタイムアウトする場合がある。対策：クエリパラメータstart_dateとend_dateで取得期間を3ヶ月以内に絞ること。KanseiLink内でのWorkaroundレポートでも「3ヶ月フィルターで800msが解消した」ことが確認されている。

5. レート制限と対処法

エンドポイント種別	レート制限	推奨対策
一般APIエンドポイント	3,600リクエスト/時間（アクセストークンごと）	エージェントタスクを時間分散。大量処理はBatch APIを活用
ウォレット・取引系	300リクエスト/5分	5分あたり300件以内に収まるようキューイング実装
請求書一括（v2 Bulk）	一般制限に準拠（1リクエストで複数件処理可能）	1リクエストで最大件数を一括発行し、リクエスト数を最小化

HTTP 429が返った場合は、レスポンスヘッダーの X-RateLimit-Reset を確認し、リセット時刻まで待機するExponential Backoffを実装すること。

6. 2026年最新アップデート

日付	変更内容	エージェントへの影響
2026-04-05	freee API v2 に /invoices/bulk（一括請求書）エンドポイントを追加。公式MCPサーバーパッケージ名も更新	月次一括請求書発行が1リクエストで完結。処理速度が大幅向上
2026-03-27	Remote MCPサーバーバージョンを追加	ローカルnpxインストールなしでクラウド型MCPとして接続可能に
2026-03-15	Invoice API v2エンドポイントをサポート	インボイス制度対応の適格請求書番号付与がAPIで自動化
2026-02-28	銀行同期のリトライロジック改善	銀行連携エラー後の自動リトライが強化。エージェントの再試行実装が不要に

7. MoneyForward Cloudとの比較

freeeと直接競合するMoneyForward Cloud（MFクラウド会計）もKanseiLink AEO評価でAAAグレードを獲得しており、成功率93%でfreeeをわずかに上回る。ただし、カバーするドメイン数と日本中小企業でのシェアにはそれぞれ特性がある。

評価軸	freee	MoneyForward Cloud
AEOグレード	AAA	AAA
成功率	90%	93% ✅ 優位
ドメインカバレッジ	5ドメイン（会計・HR・給与・経費・請求書）✅ 優位	会計・経費・請求書中心
認証方式	OAuth 2.0 PKCE（初期設定は複雑）	OAuth 2.0（同等の複雑さ）
ターゲット	小規模〜中規模事業者、個人事業主	中規模〜大規模法人
MCP起動コマンド	`npx @freee/mcp-server`	`npx @moneyforward/mcp-server`

クライアントが freee を使っているなら freee MCPを選ぶ以外の選択肢はない。MoneyForwardは大企業・経理部門寄りで、freeeは起業家・フリーランス・小規模法人に圧倒的シェアを持つ。エージェント開発では「クライアントのツール」に合わせるのが最優先だ。

まとめ — freeeはAAA、ただしOAuth設定に30分は確保せよ

freee MCPサーバーは日本の会計・HR・給与・経費・請求書を5ドメイン統合した唯一のAAAグレード公式MCPサーバーだ。2026年4月のBulk Invoices API追加とRemote MCP対応により、大規模な会計自動化エージェントの構築が現実的になっている。

ただし、OAuth 2.0 PKCE認証の初期設定とcompany_id取得フローは、APIキー1行で動くサービスと比べると確実に壁が高い。本記事の5ステップ認証ガイドと4つの落とし穴を事前に理解してから実装に入れば、立ち上げ時間を大幅に短縮できる。

また、現在進行中のauth_expired急増（ベースライン比4倍）には注意が必要だ。トークンリフレッシュロジックを実装済みの場合でも、リフレッシュ成功ログを確認することを推奨する。

freeeの最新AEOスコアとAgent Voiceデータ

リアルタイムの成功率・レイテンシ・エラートレンド・エージェントの生の声は有料コンサルティングプランで提供中。

データアクセスを申し込む