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 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`
Windows (Store版)	`%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Windows Store (Microsoft Store) 版の Claude Desktop をご利用の場合、設定ファイルのパスが異なります。freee-mcp configure は自動的に適切なパスを検出します。

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

Claude Code Plugin として使う

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

claude plugin install freee/freee-mcp

Skill のみインストールする

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

npx skills add freee/freee-mcp

グローバルインストール(-g)や特定スキルのみのインストール(-s)も可能です。

含まれるリファレンス

API	内容	ファイル数
会計	取引、勘定科目、取引先、請求書、経費申請など	31
人事労務	従業員、勤怠、給与明細、年末調整など	28
請求書	請求書、見積書、納品書	3
工数管理	プロジェクト、チーム、パートナー、工数、ユーザーなど	7
販売	案件、受注、マスタ	3

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_current_company
company_id を含まない API（例: /api/1/companies）はそのまま実行可能

コントリビューション

詳しくは CONTRIBUTING.md をご覧ください。

Contributors

開発者向け

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

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

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

技術スタック

TypeScript / Model Context Protocol SDK / OAuth 2.0 + PKCE / Zod / Bun

アーキテクチャ詳細

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

License / ライセンス

Apache-2.0

コミュニティ

質問や情報交換は Discord サーバーで行っています。お気軽にご参加ください。

Discord サーバー

freee

freee-mcp

特徴

SKILL と MCP の通信の流れ

クイックスタート

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

2. セットアップ

3. Claude Desktop に追加

Claude Code Plugin として使う

Skill のみインストールする

含まれるリファレンス

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

利用可能なツール

管理ツール

API ツール

company_id の取り扱い

コントリビューション

Contributors

開発者向け

技術スタック

アーキテクチャ詳細

License / ライセンス

コミュニティ

関連リンク

Похожие серверы

Doc Lib MCP

MCP Calendar Assistant

MCP Mistral OCR

cross-llm-mcp

Koko Credit card assistant

Mermaid-MCP

Claude Desktop Extension

MCP Personal Assistant Agent

Agile Luminary

Bear