freee MCP を Claude／Cursor に繋ぐ手順の型｜OAuth・スコープ・トークン保管と情シスの合意形成（要公式API／実装確認）
目次 クリックで開く
生成AIを単なるチャットツールとしてではなく、実務に直結した「エージェント」として活用する動きが加速しています。その中核を担う技術が、Anthropic社が提唱したModel Context Protocol (MCP)です。特に会計ソフト「freee」のデータをClaudeやCursorから直接参照・操作可能にすることは、経理業務の自動化や財務分析の爆速化において極めて高い投資対効果（ROI）を生みます。
しかし、会計データという最重要機密を扱う以上、野良の実装は許されません。本記事では、IT実務者がfreee APIをMCP経由でセキュアに接続するための「型」を、OAuth認可フローから情シスとの合意形成まで徹底的に解説します。
freee MCPをClaude／Cursorに接続する意義と構造
従来、LLMにfreeeのデータを参照させるには、CSVをエクスポートしてアップロードするか、iPaaS（MakeやZapier）を介して個別の連携フローを組む必要がありました。しかし、MCPを利用することで、AI自身が「今、freeeから試算表のデータを取ってくる必要がある」と判断し、リアルタイムにAPIを叩くことが可能になります。
なぜAPI連携ではなく「MCP」なのか
従来のAPI連携（Webhook等）は、あらかじめ定義されたトリガーに基づき動作します。一方、MCPは「AIのコンテキスト（文脈）に応じて、動的にツールを呼び出す」点が異なります。Cursorでコードを書いている最中に「現在の現預金残高に基づいた資金繰り予測コードを生成して」と指示するだけで、AIがバックグラウンドでfreee MCPサーバーを介してデータを取得し、回答を生成します。
Claude DesktopおよびCursorとの連携アーキテクチャ
MCPの構成は、大きく分けて以下の3つのコンポーネントで成り立ちます。
- MCP Client: Claude DesktopアプリやCursor（IDE）。ユーザーの指示を解釈し、ツール実行を要求する。
- MCP Server: ローカルまたはサーバー上で動作するプログラム。freee APIとの通信を仲介し、LLMが理解できる形式でデータを返す。
- Resource (freee API): 実際のデータソース。OAuth 2.0によって保護されている。
この構成により、AIモデル自体にAPIキーを渡すことなく、手元のMCP Serverが認証を肩代わりするセキュアな環境が構築できます。
freee API利用の準備：アプリ作成とスコープ定義
まずは、freee側で外部アプリケーションとしての登録が必要です。これは「誰が（どのアプリが）データにアクセスして良いか」を定義するプロセスです。
freeeアプリストアでのプライベートアプリ登録手順
- freeeアプリストアにログインし、「開発者コミュニティ」から「マイアプリ」を選択します。
- 「新規アプリ作成」をクリックし、アプリ名（例：MCP-Internal-Tool）を入力します。
- 重要：「リダイレクトURL」を設定します。ローカルでの認可を行う場合は
http://localhost:3000/callback等を設定するのが一般的です。
最小権限の原則に基づく「スコープ」の選択
情シス部門の承認を得る上で最も重要なのが「スコープ（権限範囲）」の絞り込みです。不必要に「write（書き込み）」権限を付与してはいけません。
| ユースケース | 必要なスコープ（Read） | 必要なスコープ（Write） |
|---|---|---|
| 財務状況の分析・チャット回答 | read_only |
不要 |
| 自動仕訳の提案・下書き作成 | read_only |
deals.create (取引作成) |
| マスタ参照（勘定科目・部門） | read_only |
不要 |
分析が主目的であれば read_only のみに限定することで、AIによる意図しないデータの書き換えリスクをゼロにできます。より高度な自動化、例えば「CSV手作業」を撲滅する経理自動化アーキテクチャのような仕訳連携を行う場合は、必要最低限のWrite権限を検討してください。
freee MCPサーバーの構築手順
次に、実際にfreee APIと通信するMCPサーバーを構築します。現在は TypeScript (Node.js) または Python を用いた実装が主流です。
OAuth 2.0 認可コードフローの実装
freee APIは OAuth 2.0 認可コードフローを採用しています。MCPサーバー起動時に以下のプロセスを実行します。
- ブラウザでfreeeの認可画面を開く。
- ユーザーが承認後、リダイレクトURLに
codeが返る。 codeをclient_id/client_secretと共にfreeeのトークンエンドポイントに送り、アクセストークンとリフレッシュトークンを取得する。
技術的な注意点：
freeeのアクセストークンの有効期限は 24時間 です。リフレッシュトークン（有効期限なし、ただし一度使うと新しいものに更新される）を使用して、期限切れのたびに自動更新するロジックをMCPサーバー内に組み込む必要があります。
Cursor / Claude Desktop での MCP 設定
構築したサーバーをクライアントに認識させます。claude_desktop_config.json （Windowsなら %APPDATA%/Roaming/Claude/claude_desktop_config.json）に以下のように記述します。
{
"mcpServers": {
"freee-server": {
"command": "node",
"args": ["/path/to/your/mcp-server/dist/index.js"],
"env": {
"FREEE_CLIENT_ID": "your_id",
"FREEE_CLIENT_SECRET": "your_secret",
"FREEE_REDIRECT_URI": "http://localhost:3000/callback"
}
}
}
}
Cursorの場合も、設定画面の「Features」→「MCP」から同様の設定を追加可能です。これにより、AIが freee-server というツールを介して、会計データにアクセスできるようになります。
実務で直面するエラーと解決策
実装時には、以下のようなエラーに遭遇することが多々あります。これらは設定ミスやAPIの仕様に起因するものです。
1. 401 Unauthorized (トークンの失効)
最も多いエラーです。前述の通り、アクセストークンは1日で切れます。MCPサーバー側のログを確認し、リフレッシュトークンによる更新が走っているか、あるいはリフレッシュトークン自体が無効になっていないかを確認してください。freeeの場合、リフレッシュトークンを一度使用すると新しいリフレッシュトークンが発行されるため、古いものを使い回すとエラーになります。
2. Redirect URI Mismatch
freeeアプリストアに登録したURLと、MCPサーバー側で指定した redirect_uri が一字一句（プロトコル http/https や末尾のスラッシュ含め）一致している必要があります。
3. MCPサーバーの起動失敗
環境変数が正しく渡っていない、あるいは Node.js のバージョンが古いことが原因です。claude_desktop_config.json で指定するパスは必ず絶対パスを使用してください。また、依存ライブラリの不足がないか、MCPサーバー単体で起動テストを行うことを推奨します。
こうした基盤整備は、freee会計の「経営可視化・高度連携」フェーズにおいて非常に重要なステップとなります。API連携の安定性は、そのまま業務の信頼性に直結するからです。
情シス・セキュリティ部門との合意形成のポイント
技術的な準備が整っても、組織内で利用許可を得るという高いハードルがあります。情シス部門が懸念するのは「データの流出」と「AIの学習」です。
データガバナンス：AIは学習されるのか？
AnthropicのClaude（API経由およびProプランの特定設定）やCursorのビジネスプラン（Privacy Mode）では、入力したデータがモデルの学習に利用されないことが明記されています。この点を、公式のプライバシーポリシーや利用規約を添えて説明することが不可欠です。「プロンプトに含まれる会計データは、あくまで一時的な推論にのみ使用され、将来のモデル改善には利用されない」という保証が合意の第一歩です。
アクセスログの監査と権限分離
freee側では「誰が作成したアプリが」「いつ」「どのデータに」アクセスしたかがログに残ります。また、MCPサーバー側でもリクエストログを出力するように設計しておくことで、万が一の事態に対するトレーサビリティを確保できます。これは、退職者のアカウント削除漏れを防ぐID管理の自動化と同様、企業のガバナンス体制の一環として説明すべき内容です。
まとめ：AI×会計データが切り拓く新時代
freee MCPの導入は、単なるツールの接続ではありません。AIが自社の財務状況をリアルタイムに把握し、最適な経営判断の補助を行う「自律型バックオフィス」への転換点です。OAuth認可、スコープの最小化、そして情シスとの丁寧な対話。これらを一つずつクリアしていくことで、安全かつ強力なAI駆動型の業務環境が実現します。
まずは read_only 権限での接続から始め、小さな成功体験を積み重ねていくことをお勧めします。技術的な不確実性は、公式ドキュメントと実機検証で一つずつ潰していく。それが、最高峰のIT実務担当者に求められる姿勢です。
実務導入前に確認すべき「技術仕様」と「運用チェックリスト」
freee MCPの実装をスムーズに進めるためには、コードを書く前にfreee API特有の挙動を理解しておく必要があります。特に認証周りの仕様を誤解すると、運用開始直後にシステムが停止するリスクがあります。
1. リフレッシュトークンの「一度きり」仕様に注意
freee APIの認可フローで最も躓きやすいのが、リフレッシュトークンの取り扱いです。多くのSaaS APIと異なり、freeeのリフレッシュトークンは「一度使用すると無効になり、新しいトークンが発行される」という仕様（Rotation）を採用しています。
- 誤解： 最初に取得したリフレッシュトークンを
.env等に固定で書き込んで使い回せる。 - 正解： トークン更新のたびに、新しく発行されたリフレッシュトークンをデータベースやJSONファイルに上書き保存し、次回の更新では新しい方を使わなければならない。
2. 導入判断のためのセキュリティ・機能比較表
情シス部門との協議において、なぜ他の手段ではなく「MCP」なのかを説明するための比較表です。組織のポリシーに合わせて最適な構成を選択してください。
| 比較項目 | MCP (Claude/Cursor) | CSVアップロード | iPaaS (Make/Zapier等) |
|---|---|---|---|
| データの即時性 | リアルタイム（API直結） | エクスポート時点のデータ | トリガー実行時のデータ |
| 柔軟性 | 極めて高い（AIが判断） | 低い（手動操作のみ） | 中（定義済みのフロー） |
| 学習への利用 | 設定により除外可能 | 手動アップロード時に注意 | API経由のため原則除外 |
| 構築難易度 | 中〜高（要プログラミング） | 低（非エンジニア可） | 低〜中（ノーコード） |
3. 実装の参考になる公式リソース
実装時には必ず以下の公式ドキュメントを参照してください。特にレートリミット（リクエスト回数制限）は、大量のデータをAIに読み込ませる際に考慮が必要です。
- freee API スタートガイド（公式）：認可フローの基本概念が網羅されています。
- 会計API レートリミットについて：AIのループ実行によるエラーを防ぐために確認必須です。
- Model Context Protocol 公式ドキュメント（英語）：MCPの最新仕様とSDKの使い方が確認できます。
また、会計データ以外のSaaS連携についても、モダンデータスタックを活用したツール選定の考え方を適用することで、MCPとデータウェアハウスを組み合わせた、より高度な意思決定基盤を構築可能です。
ご相談・お問い合わせ
本記事の内容を自社の状況に当てはめたい場合や、導入・運用の設計を一緒に整理したい場合は、当社までお気軽にご相談ください。担当より折り返しご連絡いたします。