freee MCP Server
freee会計APIとClaude MCPを連携するサーバー。
概要
- 目的: 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歓迎です。