freee MCP Server

freee会計APIとClaude MCPを連携するサーバー。

License: MIT Python 3.13+

概要

目的: Claudeからfreee会計データを操作（取引作成・口座確認・証憑アップロード・財務諸表取得等）
認証: OAuth 2.0 PKCE（ブラウザ認証）
token管理: 暗号化保存 + 自動リフレッシュ
実装言語: Python 3.13+

機能

MCPツール

ツール名	説明	freee API
`list_companies`	事業所一覧取得	GET /api/1/companies
`list_accounts`	勘定科目一覧	GET /api/1/account_items
`list_walletables`	口座一覧	GET /api/1/walletables
`list_wallet_txns`	口座明細一覧（元明細テキスト含む）	GET /api/1/wallet_txns
`list_deals`	取引一覧	GET /api/1/deals
`list_invoices`	請求書一覧	GET /api/1/invoices
`get_partners`	取引先一覧	GET /api/1/partners
`create_deal`	取引作成	POST /api/1/deals
`upload_receipt`	証憑アップロード	POST /api/1/receipts
`get_trial_balance_bs`	貸借対照表（BS）	GET /api/1/reports/trial_bs
`get_trial_balance_pl`	損益計算書（PL）	GET /api/1/reports/trial_pl

OAuth 2.0 PKCE認証フロー

1. ブラウザで認証URL起動 2. freeeログイン → 認可コード取得 3. アクセストークン取得 → 暗号化保存 4. リフレッシュトークンで自動更新

セットアップ

1. freee Developersでアプリ登録

https://developer.freee.co.jp/

アプリケーション名: 任意（例: freee-mcp-server）
リダイレクトURI: http://localhost:8080/callback
必要なスコープ:
- read:companies - 事業所情報
- read:accounts - 勘定科目
- read:walletables - 口座情報
- read:wallet_txns - 口座明細
- read:deals - 取引参照
- write:deals - 取引作成
- read:invoices - 請求書参照
- read:partners - 取引先参照
- write:receipts - 証憑アップロード
- read:reports - 財務諸表

CLIENT_ID と CLIENT_SECRET を取得してください。

2. 環境変数設定

cp .env.example .env # .env を編集

FREEE_CLIENT_ID=your_client_id FREEE_CLIENT_SECRET=your_client_secret FREEE_REDIRECT_URI=http://localhost:8080/callback TOKEN_ENCRYPTION_KEY=generate_random_32_bytes FREEE_COMPANY_ID=your_company_id

暗号化キーの生成:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

3. 依存関係のインストール

pip install -e .

4. 初回認証

python src/auth.py

ブラウザが開き、freeeログイン → tokenが ~/.freee-mcp/tokens.enc に保存されます。

5. MCPサーバー起動

python src/server.py

6. Claude側設定

Claude Desktop の claude_desktop_config.json または Claude Code の .mcp.json:

{ "mcpServers": { "freee": { "command": "python", "args": ["/path/to/freee-mcp/src/server.py"], "env": { "FREEE_CLIENT_ID": "your_client_id", "FREEE_CLIENT_SECRET": "your_client_secret", "FREEE_COMPANY_ID": "your_company_id", "TOKEN_ENCRYPTION_KEY": "your_encryption_key" } } } }

Claude Code Skills

Claude Codeで使える便利なSkillを同梱しています。

subscription-analyzer

口座明細からサブスクリプションを自動検出・分析します。

/subscription-analyzer

機能:

80+サービスの自動検出（AI/ML, 開発ツール, クラウド等）
カテゴリ別コスト集計
重複課金・解約候補の提案

検出対象例:

カテゴリ	サービス
AI/ML	ANTHROPIC, OPENAI, MIDJOURNEY, CURSOR
クラウド	AWS, GCP, AZURE, VERCEL, FLY.IO
開発ツール	GITHUB, NEON, SUPABASE, UPSTASH
生産性	NOTION, SLACK, ASANA, FIGMA

詳細: .claude/skills/subscription-analyzer/SKILL.md

ディレクトリ構成

freee-mcp/ ├── README.md ├── SETUP.md # 詳細セットアップガイド ├── LICENSE ├── pyproject.toml ├── .env.example ├── src/ │ ├── __init__.py │ ├── server.py # MCPサーバーのメイン │ ├── auth.py # OAuth 2.0 PKCE認証 │ ├── token_store.py # トークン暗号化保存 │ ├── freee_client.py # freee APIクライアント │ └── tools.py # MCPツール定義 ├── .claude/skills/ │ └── subscription-analyzer/ # サブスク分析Skill │ ├── SKILL.md │ └── patterns.yml └── tests/ └── test_integration.py

使用例

口座明細の取得（サブスク分析に便利）

Claude: freeeの口座明細を取得して、サブスクリプションを確認して

→ list_wallet_txns で明細テキスト（例: "ANTHROPIC_カード13"）を含む明細を取得

財務諸表の確認

Claude: 2024年度の損益計算書を見せて

→ get_trial_balance_pl で損益計算書を取得

取引の作成

Claude: 今日付けで外注費30,000円の取引を作成して

→ create_deal で取引を自動作成

技術仕様

token暗号化

暗号化方式: Fernet（symmetric encryption）
保存場所: ~/.freee-mcp/tokens.enc
キー管理: 環境変数 TOKEN_ENCRYPTION_KEY（32 bytes）

エラーハンドリング

401 Unauthorized: 自動リフレッシュ → 再実行
429 Too Many Requests: 指数バックオフ（2^n秒）
500 Server Error: 3回リトライ

ライセンス

MIT License - 詳細は LICENSE を参照

貢献

Issue・Pull Request歓迎です。

freee MCP Server

freee MCP Server

概要

機能

MCPツール

OAuth 2.0 PKCE認証フロー

セットアップ

1. freee Developersでアプリ登録

2. 環境変数設定

3. 依存関係のインストール

4. 初回認証

5. MCPサーバー起動

6. Claude側設定

Claude Code Skills

subscription-analyzer

ディレクトリ構成

使用例

口座明細の取得（サブスク分析に便利）

財務諸表の確認

取引の作成

技術仕様

token暗号化

エラーハンドリング

ライセンス

貢献

関連リンク

Resources

New MCP Servers

Latest Blog Posts

MCP directory API