freee MCPの設定でつまずく8つのポイントと解決法【Claude Code/Cursor】

freee MCPを使えば、AIエージェントが取引の記帳・経費・給与データを直接操作できる。しかし「設定したのに動かない」「APIが呼べない」といった声が開発者コミュニティに多数上がっている。詰まる箇所はほぼ共通しており、1つずつ潰せば確実に動く。

事前準備チェックリスト

設定を始める前に以下を確認しておくと、後のトラブルを防げる。

詰まりポイント8選と解決法

① Client Secret / トークンのコピペミス・余分な空白

原因：freee Developer ConsoleからClient IDやClient Secretをコピーした際に、文字列の前後に半角スペースや改行が混入しやすい。JSONの設定ファイルに直接貼るとダブルクォート内の余分な文字がそのまま渡り、認証に失敗する。

対処：

• コピー後にテキストエディタのプレーンテキストモードで一度確認し、前後の空白を取り除く
• 環境変数（.envファイルや OSのシェル変数）に設定する場合も、代入文の末尾に空白が入っていないか確認する
• 設定ファイルの文字列を echo コマンドで出力するなど、実際に渡っている値をデバッグすること

② OAuthスコープの設定漏れ

原因：freee APIのOAuth2では会計・人事・決済など機能ごとにスコープが分かれており、アプリ登録時に必要なスコープを明示的に有効化しなければならない。デフォルトでは全スコープが付与されないため、使いたい機能のスコープが足りていない状態になりやすい。

対処：

• freee Developer Consoleの当該アプリの設定ページで、利用予定の機能（会計・人事・販売管理など）に対応するスコープにチェックが入っているか確認する
• スコープを追加した後はアクセストークンを再取得する必要がある（既存トークンには新スコープが反映されない）
• 必要スコープの一覧は公式READMEに記載があるため参照すること

③ Node.js / npx の実行環境不足

原因：freee MCPはNode.jsランタイムで動作する。Node.jsが未インストール、バージョンが古い、またはnpxがPATHに通っていない環境では起動できない。

対処：

• node --version と npx --version でインストール状況を確認する
• バージョン要件は時期によって変わるため、公式READMEの「Requirements」セクションで必ず確認する
• バージョン管理に nvm や volta を使っている場合、MCPクライアントが起動する環境のPATHにNodeが含まれていないことがある。シェルのプロファイル設定を確認すること

④ MCP 設定ファイル（JSON）の記法ミス・パス誤り

原因：MCP設定ファイル（Claude Codeなら ~/.claude/settings.json、Cursorなら mcp.json など）のJSON構文エラーや、コマンドのパス誤りが原因。JSONはカンマ1つの過不足で丸ごと読み込みに失敗する。

対処：

• 設定ファイルを保存したら node -e "JSON.parse(require('fs').readFileSync('<設定ファイルパス>', 'utf8'))" などで構文チェックを行う
• コマンドのパスは絶対パスで記述するか、コマンド単体をターミナルで実行して動作を確認する
• 末尾カンマ（trailing comma）はJSONでは構文エラーになるため削除する
• 設定ファイルの正確な構造は公式READMEのサンプルをそのままコピーして使うのが最も安全

⑤ ローカル版とリモート版の混同

原因：freee MCPには「ローカルで直接npxを実行する方式」と「リモートMCPとして接続する方式」があり、それぞれ設定ファイルの書き方・認証の流れが異なる。どちらを使うか決めずに両方の手順を混在させると動作しない。

対処：

• まず公式READMEの「Installation」セクションを読み、自分の環境・用途に合った方式を選ぶ
• 一方の設定を試しているときは、もう一方の設定が残らないよう設定ファイルを整理する
• 方式によってリダイレクトURIの設定も変わるため、Developer Consoleの登録内容も合わせて確認する

⑥ 権限不足で特定の API が呼べない

原因：freeeには事業所内のユーザー権限設定があり、ログインユーザーに「経費承認」「給与確認」「レポート閲覧」などの権限が付与されていない場合、MCPを経由しても同様に拒否される。MCPは認証済みユーザーの権限を引き継ぐため、APIで許可されていない操作は実行できない。

対処：

• freeeの事業所設定でMCPに使うアカウントの権限を確認・修正する（管理者への依頼が必要なケースあり）
• スコープと事業所内権限は別物であることを意識する（スコープはAPIアプリの許可範囲、権限はfreee内のユーザー設定）
• テスト時は管理者権限を持つアカウントで試すと問題の切り分けがしやすい

⑦ 複数アプリ連携時のID取り違え

原因：Developer Consoleで複数のアプリを作成・テストしている場合、Client IDやClient Secretが複数存在する。設定ファイルに別アプリのCredentialを使ってしまうと、意図しない事業所・スコープで動いてしまう。

対処：

• Developer Consoleでアプリ名を「freee-mcp-本番」「freee-mcp-テスト」など用途別に明確につける
• 設定ファイル内のClient IDをDeveloper Consoleで照合し、目的のアプリと一致するか確認する
• 環境変数名も衝突しないようアプリ別にプレフィックスをつけるなど管理を整理する

⑧ 本番データでのテスト（サンドボックスを使う）

原因：freeeは本番環境とサンドボックス環境を提供しているが、設定を急いでいると本番環境のCredentialをそのままテストに使ってしまいがち。書き込み系API（取引登録・経費承認など）を本番で誤実行するとデータ復旧が困難になる。

対処：

• 動作確認・開発段階では必ずfreee サンドボックス環境のCredentialを使う
• サンドボックスのClient IDと本番のClient IDは別物のため、設定ファイルを環境別に分けて管理する
• サンドボックスの利用方法はfreee Developer Portalで確認する

それでも動かない時の切り分け手順

8つのポイントを確認しても解決しない場合は、以下の順で切り分けると原因が絞り込みやすい。

1. MCPサーバーのログを確認する：Claude CodeやCursorはMCPサーバーのstderr出力をログとして確認できる場合がある。エラーメッセージをそのまま読むのが最短
2. コマンドをターミナルで単体実行する：MCPクライアント経由ではなく、ターミナルでMCPサーバー起動コマンドを直接叩いてエラーが出るか確認する
3. 公式GitHubのIssueを検索する：github.com/freee/freee-mcp/issuesに同様の症状が報告されていないか確認する
4. READMEのセットアップ手順を最初からやり直す：「設定したつもり」の状態を一度リセットし、公式手順の通りに順番通りに実施し直す

よくある質問

まとめ