# freee MCP Server
freee会計APIとClaude MCPを連携するサーバー。
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
## 概要
- **目的**: 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. 環境変数設定
```bash
cp .env.example .env
# .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
```
暗号化キーの生成:
```bash
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```
### 3. 依存関係のインストール
```bash
pip install -e .
```
### 4. 初回認証
```bash
python src/auth.py
```
ブラウザが開き、freeeログイン → tokenが `~/.freee-mcp/tokens.enc` に保存されます。
### 5. MCPサーバー起動
```bash
python src/server.py
```
### 6. Claude側設定
Claude Desktop の `claude_desktop_config.json` または Claude Code の `.mcp.json`:
```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](.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](./LICENSE) を参照
## 貢献
Issue・Pull Request歓迎です。
## 関連リンク
- [freee API ドキュメント](https://developer.freee.co.jp/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Code](https://claude.ai/code)
