MCP 服务器

@him0/freee-mcp

An MCP server and Claude plugin that enables interaction with freee APIs for accounting, human resources, invoicing, and more. It provides secure OAuth 2.0 authentication and integrates detailed API reference skills to support tasks like creating invoices and managing company data through natural language.

README

@him0/freee-mcp

freee API を Claude から使えるようにする MCP サーバー & Claude Plugin です。

MCP サーバー（API 呼び出し機能）と skill（API リファレンス）を組み合わせて利用することを想定しています。

Note: このプロジェクトは開発中であり、予期せぬ不具合が発生する可能性があります。問題を発見された場合は Issue として報告していただけると幸いです。プルリクエストも歓迎しています。

特徴

MCP サーバー: freee API を Claude Desktop / Claude Code から直接呼び出し
Claude Plugin: 詳細な API リファレンスドキュメント付きスキルを提供
複数 API 対応: 会計・人事労務・請求書・工数管理・販売の5つの freee API をサポート
OAuth 2.0 + PKCE: セキュアな認証フロー、トークン自動更新
複数事業所対応: 事業所の動的切り替えが可能

SKILL と MCP の通信の流れ

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

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

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

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

    Note over Claude,MCP: 2. MCP Tool で API を実行
    Claude->>MCP: freee_api_get 呼び出し<br/>path: /api/1/deals
    MCP->>MCP: OpenAPI スキーマで検証
    MCP->>MCP: 認証トークン付与

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

    MCP-->>Claude: 取引データ
    Claude-->>User: 結果を整形して表示

この仕組みにより：

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

クイックスタート

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

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

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

2. セットアップ

npx @him0/freee-mcp configure

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

3. Claude Desktop に追加

configure が出力する設定を Claude Desktop の設定ファイルに追加:

OS	設定ファイルパス
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "freee": {
      "command": "npx",
      "args": ["@him0/freee-mcp"]
    }
  }
}

⚠️ 環境変数での設定について環境変数（FREEE_CLIENT_ID、FREEE_CLIENT_SECRET など）を使った設定は非推奨です。代わりに npx @him0/freee-mcp configure を実行して設定ファイルに移行してください。環境変数設定は将来のバージョンで削除される予定です。

Claude Plugin として使う

Claude Code でプラグインとしてインストールすると、API リファレンス付きのスキルが利用できます:

npx add-skill him0/freee-mcp

add-skill は Claude Code、Cursor、OpenCode など複数のコーディングエージェントに対応したスキルインストーラーです。グローバルインストール(-g)や特定スキルのみのインストール(-s)も可能です。

含まれるリファレンス

API	内容	ファイル数
会計	取引、勘定科目、取引先、請求書、経費申請など	31
人事労務	従業員、勤怠、給与明細、年末調整など	27
請求書	請求書、見積書、納品書	3
工数管理	ユーザー情報	1
販売	案件、受注	2

Claude との会話中に API の使い方を質問すると、これらのリファレンスを参照して正確な情報を提供します。

データ作成のベストプラクティス

請求書や経費精算など、同じ形式のデータを繰り返し作成する場合は、以前に作成したデータを参照することで効率的に作業できます：

請求書作成: 過去の請求書を取得して、取引先・品目・税区分などを参考にする
経費精算: 過去の申請を参照して、勘定科目や部門の指定を正確に行う
取引登録: 類似の取引を参考にして、入力ミスを防ぐ

例: 「先月の○○社への請求書を参考に、今月分を作成して」

利用可能なツール

管理ツール

ツール	説明
`freee_authenticate`	OAuth 認証を実行
`freee_auth_status`	認証状態を確認
`freee_clear_auth`	認証情報をクリア
`freee_set_current_company`	事業所を切り替え
`freee_get_current_company`	現在の事業所を表示
`freee_list_companies`	事業所一覧を取得
`freee_current_user`	現在のユーザー情報

API ツール

HTTPメソッドごとのシンプルなツール構成:

ツール	説明	例
`freee_api_get`	データ取得	`/api/1/deals`
`freee_api_post`	新規作成	`/api/1/deals`
`freee_api_put`	更新	`/api/1/deals/123`
`freee_api_delete`	削除	`/api/1/deals/123`
`freee_api_patch`	部分更新	`/api/1/deals/123`
`freee_api_list_paths`	エンドポイント一覧	-

パスは OpenAPI スキーマに対して自動検証されます。

company_id の取り扱い

リクエスト（パラメータまたはボディ）に company_id を含める場合、現在の事業所と一致している必要があります。不一致の場合はエラーになります。

事業所の確認: freee_get_current_company
事業所の切り替え: freee_set_company
company_id を含まない API（例: /api/1/companies）はそのまま実行可能

開発者向け

git clone https://github.com/him0/freee-mcp.git
cd freee-mcp
pnpm install

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

# API リファレンスの再生成
pnpm generate:references