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歓迎です。

関連リンク

• freee API ドキュメント
• Model Context Protocol
• Claude Code