@yamitzky/freee

freee API を AI エージェントから操作するための CLI & Agent Skill です。

freee/freee-mcp を元に、MCP サーバーを廃止して CLI + Agent Skill アーキテクチャに再構築した非公式フォークです。

Note: このプロジェクトは非公式フォークです。また、CLIの作者は会計APIしか使っておらず、十分なテストを行っていません。

特徴

• freee CLI: シェルから直接 freee API を操作（トークン効率の高いコンパクト出力）
• Agent Skill: CLI の使い方をガイドするスキルを提供
• 複数 API 対応: 会計・人事労務・請求書・工数管理・販売の5つの freee API をサポート
• OAuth 2.0 + PKCE: セキュアな認証フロー、トークン自動更新

SKILL と CLI の連携の流れ

Claude Code では、SKILL（API リファレンス）と CLI（API 呼び出し）を組み合わせて利用します。

sequenceDiagram
    participant User as ユーザー
    participant Claude as Claude Code
    participant Skill as Agent Skill<br/>(API リファレンス)
    participant CLI as freee CLI<br/>(ローカル)
    participant API as freee API

    User->>Claude: リクエスト<br/>「取引一覧を取得して」

    Note over Claude,Skill: 1. SKILL からリファレンスを取得
    Claude->>Skill: freee-cli-skill 呼び出し
    Skill-->>Claude: API リファレンス注入<br/>(エンドポイント、パラメータ仕様)

    Note over Claude,CLI: 2. CLI で API を実行
    Claude->>CLI: freee accounting get deals<br/>type==income limit==10

    Note over CLI,API: 3. freee API への通信
    CLI->>API: GET /api/1/deals<br/>Authorization: Bearer xxx
    API-->>CLI: JSON レスポンス

    CLI-->>Claude: コンパクトなテーブル出力
    Claude-->>User: 結果を整形して表示

この仕組みにより：

• SKILL: 必要な API リファレンスを段階的にコンテキストに注入（コンテキスト効率化）
• CLI: 認証・リクエスト検証・API 呼び出しを担当（コンパクト出力でトークン効率化）

クイックスタート

1. freee アプリケーションの登録

freee アプリストア で新しいアプリを作成:

• コールバックURL: http://127.0.0.1:54321/callback
• Client ID と Client Secret を取得
• 必要な権限にチェック

2. セットアップ

npx @yamitzky/freee configure

対話式ウィザードが認証情報の設定、OAuth認証、事業所選択を行います。

3. CLI を使う

npm install -g @yamitzky/freee
# または
bun install -g @yamitzky/freee

freee auth status              # 認証状態を確認
freee accounting ls            # エンドポイント一覧
freee accounting get deals     # 取引一覧を取得
freee --help                   # ヘルプ

Agent Skill のインストール

コーディングエージェント（Claude Code, Cursor, OpenCode など）で API リファレンス付きスキルを利用する場合は、skills でインストールできます。

npx skills add yamitzky/freee-cli

freee CLI コマンド

認証・事業所

| コマンド | 説明 | |---------|------| | freee auth login | OAuth 認証 | | freee auth status | 認証状態を確認 | | freee auth logout | ログアウト | | freee company ls | 事業所一覧 | | freee company set <id> | 操作対象の事業所を設定 | | freee company current | 現在の事業所を表示 |

API 操作

| コマンド | 説明 | |---------|------| | freee <service> ls [filter] | エンドポイント一覧 | | freee <service> get <path> key==val | クエリ付き GET | | freee <service> post <path> key=val | POST リクエスト | | freee <service> post receipts <file> | ファイルアップロード | | freee <service> put <path> -d '{}' | PUT リクエスト | | freee <service> delete <path> | DELETE リクエスト | | freee <service> <path> --help | メソッド一覧を表示 | | freee <service> get <path> --help | パラメータのドキュメント | | freee <service> get <path> --help --response | レスポンスも含めて表示 | | freee <service> get <path> --spec | 生の OpenAPI スキーマ |

service: accounting, hr, invoice, pm, sm

company_id の取り扱い

company_id は現在の事業所が自動的に使用されます。明示的に指定すると別の事業所を操作できます。

• 事業所の確認: freee company current
• 事業所の切り替え: freee company set <id>

開発者向け

git clone https://github.com/yamitzky/freee-cli.git
cd freee-cli
bun install

bun run dev           # 開発サーバー（ウォッチモード）
bun run build         # ビルド
bun run typecheck    # 型チェック
bun run lint          # リント
bun run test:run      # テスト

技術スタック

TypeScript / OAuth 2.0 + PKCE / Zod / Bun

アーキテクチャ詳細

プロジェクトのアーキテクチャ、内部構造、開発ガイドラインについては CLAUDE.md を参照してください。

License / ライセンス

このフォークには、freee K.K. による freee/freee-mcp のコードが含まれており、当該コードは Apache License 2.0 に基づいて提供されています。法令上許容される限りにおいて、私がこのフォークに加えた独自の変更および追加部分については、著作権が発生するとは考えておらず、CC0 1.0 に基づき、著作権その他の関連する権利を放棄します。

また、APIの利用についてはfreee API 利用規約 に準拠します。

関連リンク

• フォーク元: freee/freee-mcp -- オリジナルの MCP サーバー実装
• freee API ドキュメント
• 紹介記事: Public API を MCP化するとき Agent Skill 併用が良さそう -- フォーク元の設計思想