AI导哈

会计API MCP服务器

一个用于从Claude Code直接访问freee会计数据的MCP服务器，附带确定申报审查插件，适用于企业会计数据处理和税务审查。

  • by morodomi
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 morodomi/freee-mcp

使用说明

freee MCP Server

確定申告用のfreee会計API MCPサーバー + 確定申告レビュープラグイン

機能

MCP サーバー

freee 会計のデータを Claude Code から直接参照できる MCP（Model Context Protocol）サーバー。

  • 認証: OAuth 2.0 による freee API 認証（認証後に利用可能な事業所を自動表示）
  • 取引: 一覧取得・詳細表示・フィルタリング（取引先名を自動解決）
  • 固定資産: 一覧取得（減価償却の確認に）
  • 分析: 収支サマリー・科目別集計・月次推移
  • アドバイス: 経費最適化の提案

tax-advisor プラグイン

3つの専門エージェントが並行で帳簿をレビューする確定申告チェックスキル。

  • P/L分析: 前年比較、雑費比率、経費集中度、月次異常検知
  • 取引チェック: 未決済取引、期間外取引、大額取引（固定資産計上の要否）
  • コンプライアンス: 按分計上リマインド、要注意科目、経費最適化ヒント

前提条件

ツール バージョン 確認コマンド
Python 3.11 以上 python3 --version
uv 最新推奨 uv --version
Claude Code 最新 claude --version

uv が未インストールの場合:

curl -LsSf https://astral.sh/uv/install.sh | sh

セットアップ

1. freee 開発者サイトでアプリ登録

  1. freee Developers にログイン（freee 本体のアカウントでログインできます。別途アカウント作成は不要です）
  2. 「アプリ管理」→「新規作成」でアプリを作成
  3. Client ID と Client Secret をメモ
  4. アプリ設定画面の「コールバック URL」欄に urn:ietf:wg:oauth:2.0:oob を入力して保存

2. インストール

git clone https://github.com/morodomi/freee-mcp
cd freee-mcp
uv sync

3. 環境変数設定

cp .env.example .env

.env を編集して freee アプリの Client ID / Client Secret を記入します:

FREEE_CLIENT_ID=your_client_id
FREEE_CLIENT_SECRET=your_client_secret

シェル設定ファイル（~/.bashrc / ~/.zshrc）に export で書く方法でも動作します。両方設定した場合はシェル設定（OS環境変数）が優先されます。

4. Claude Code に MCP サーバーを登録

freee-mcp ディレクトリ内で以下を実行:

claude mcp add freee-mcp -- uv run --directory $(pwd) freee-mcp

--directory は MCP サーバーが .env ファイルを見つけるために必要です。別ディレクトリから Claude Code を起動した場合でも正しく読み込まれます。

5. 初回認証

Claude Code 内で認証を行います:

freee にログインして

以下の手順で認証が進みます:

  1. 認証 URL が表示されるので、ブラウザで開く
  2. freee にログインし、アプリへのアクセスを許可
  3. 表示された認証コード（abc123def456 のような英数字の文字列）をコピー
  4. Claude Code に認証コードを伝える（例: 認証コードは abc123def456 です）

認証が成功すると、利用可能な事業所の一覧と company_id が表示されます。この company_id は各種ツールで使用します。

認証トークンは以下の場所に保存され、次回以降は自動的に使用されます。有効期限が切れた場合は自動でリフレッシュされます。

OS 保存先
macOS ~/Library/Application Support/freee-mcp/tokens.json
Linux ~/.local/share/freee-mcp/tokens.json

6. tax-advisor プラグインのインストール（任意）

確定申告レビュー機能を使う場合、freee-mcp ディレクトリ内で:

claude plugin add ./plugins/tax-advisor

インストールの確認:

claude plugin list

使い方

Claude Code で freee のデータを自然言語で参照できます。

日常チェック

freee の認証状態を確認して
今月の未決済取引を一覧で見せて
先月の収支サマリーを教えて

確定申告準備

2025年の収支サマリーを教えて
2025年の経費を科目別に集計して
月次の収支推移を見せて
固定資産の一覧を見せて
経費の最適化アドバイスをちょうだい

包括レビュー（tax-advisor プラグイン）

/tax-review

3つの専門エージェントが並行でレビューを実行し、結果を severity でソートして表示します:

エージェント チェック内容
pl-reviewer 前年比較、雑費比率、経費集中度、月次異常
deal-reviewer 未決済取引、期間外取引、大額取引
compliance-reviewer 按分計上、要注意科目、経費最適化

レビュー結果の severity:

区分 意味 対応
要修正 (critical) 確定申告前に修正が必要 freee で該当取引を修正
要確認 (warning) 内容を確認し判断が必要 問題なければそのまま
参考 (info) 参考情報・最適化提案 余裕があれば対応

MCP ツール一覧

内部で以下の MCP ツールが呼び出されます:

認証

ツール 説明
freee_auth_login OAuth 認証 URL を取得（ブラウザで開いて認証コードを取得）
freee_auth_code 認証コードをトークンに交換（成功時に事業所一覧を表示）
freee_auth_status 認証状態を確認（トークン有効期限を返す）
freee_auth_logout ログアウト（保存トークンを削除）

取引

ツール 引数 説明
freee_list_deals company_id, partner_id?, status?, deal_type?, start_issue_date?, end_issue_date?, limit?, offset? 取引一覧を取得（取引先名を自動解決）。status で決済状態（settled/unsettled）、deal_type で種別（income/expense）をフィルタ可能
freee_get_deal company_id, deal_id 取引の詳細を取得

固定資産

ツール 引数 説明
freee_list_fixed_assets company_id 固定資産の一覧を取得。10万円以上の購入品の計上状況や減価償却の確認に使用

分析

ツール 引数 説明
freee_income_expense_summary company_id, start_date, end_date 指定期間の収入・支出・利益サマリーを取得
freee_account_summary company_id, start_date, end_date 科目別の金額集計を取得（金額降順）
freee_monthly_trend company_id, start_date, end_date 月次の収入・支出・利益推移を取得

アドバイス

ツール 引数 説明
freee_get_optimization_advice company_id, start_date, end_date 経費の内訳分析と最適化アドバイスを取得

カスタマイズ

プロジェクトルートに .claude/kakutei-config.yaml を作成して閾値を調整できます:

# 雑費比率の閾値を緩める（デフォルト: 10%）
misc_expense_ratio: 15

# 按分対象に科目を追加
home_office_accounts:
  - "通信費"
  - "地代家賃"
  - "水道光熱費"
  - "車両費"

全閾値のデフォルト値は plugins/tax-advisor/skills/tax-review/reference-rules.md を参照。

トラブルシューティング

認証エラー

ConfigurationError: FREEE_CLIENT_ID is required

環境変数が設定されていません。「セットアップ > 3. 環境変数設定」を確認してください。

# 設定を確認
echo $FREEE_CLIENT_ID
echo $FREEE_CLIENT_SECRET

.env ファイルを使っている場合は、claude mcp add 時に --directory でプロジェクトルートを指定しているか確認してください。

「トークンのリフレッシュに失敗しました」

保存済みトークンが無効になっています。再ログインしてください:

freee からログアウトして
freee にログインして

接続エラー

APIError (401): Unauthorized

トークンが期限切れです。通常は自動リフレッシュされますが、失敗した場合は再ログインしてください。

APIError (403): Forbidden

freee アプリの権限が不足しています。freee Developers でアプリの権限設定を確認してください。

APIError (404): Not Found

company_id が正しいか確認してください。Claude Code で 事業所を確認して と聞くと、利用可能な事業所の一覧を取得できます。

MCP サーバーが起動しない

# 依存関係を再インストール
uv sync

# 直接起動して確認
uv run freee-mcp

tax-advisor プラグインが認識されない

# インストール状況を確認
claude plugin list

# 再インストール（freee-mcp ディレクトリ内で）
claude plugin add ./plugins/tax-advisor

セキュリティ

読み取り専用

全ての MCP ツールは 読み取り専用（GET リクエストのみ）です。freee のデータを変更・削除することはありません。

トークンの保管

  • OAuth トークンは OS に応じた場所に保存（macOS: ~/Library/Application Support/freee-mcp/tokens.json、Linux: ~/.local/share/freee-mcp/tokens.json）
  • このファイルには freee API へのアクセストークンが含まれるため、他人と共有しないでください
  • .gitignore に tokens.json が含まれており、誤ってコミットされることはありません

環境変数

  • FREEE_CLIENT_ID と FREEE_CLIENT_SECRET は .env ファイルまたはシェル設定で管理
  • .env は .gitignore に含まれており、リポジトリにコミットされません

データの処理

  • freee から取得したデータは Claude Code のセッション内でのみ処理されます
  • 外部サービスへのデータ送信は行いません

開発

uv sync --all-extras
uv run pytest
uv run mypy src --strict
uv run ruff check src tests

ライセンス

MIT

相关 MCP