What is Freee Mcp

freee-mcp is an implementation that provides the freee API as a Model Context Protocol (MCP) server. It automatically exposes the endpoints of the freee API as MCP tools using OpenAPI definitions.

Use cases

Use cases for freee-mcp include automating financial data retrieval, integrating accounting software with other applications, and enhancing business workflows through API interactions.

How to use

To use freee-mcp, clone the repository, install the dependencies using pnpm, set the required environment variables, and start the server. You can register it as an MCP server in applications like Claude or VSCode by adding specific configurations.

Key features

Key features include automatic publication of freee API endpoints as MCP tools, automatic validation of API requests using Zod, and error handling with response formatting.

Where to use

freee-mcp can be used in various fields that require integration with the freee API, such as accounting, finance, and business management applications.

freee-mcp

freee APIをModel Context Protocol (MCP)サーバーとして提供する実装です。OpenAPI定義を使用して、freee APIのエンドポイントを自動的にMCPツールとして公開します。

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

概要

このプロジェクトは以下の機能を提供します:

• freee APIのエンドポイントをMCPツールとして自動公開
• OAuth 2.0 + PKCE認証による安全なAPI接続
• 永続コールバックサーバーによる認証フロー
• 複数事業所対応: 同一ユーザーでの複数事業所への動的切り替え
• 自動トークン管理（保存・更新・有効期限チェック）
• APIリクエストの自動バリデーション（Zod使用）
• エラーハンドリングとレスポンス整形

必要要件

• Node.js v22
• pnpm

インストール

git clone [repository-url]
cd freee-mcp
pnpm install

環境設定

OAuth 2.0 認証

OAuth 2.0 + PKCE フローを使用した認証が必要です。以下の手順で設定してください:

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

• freee アプリストア にアクセス
• 新しいアプリケーションを作成
• 以下の設定を行う:
  • リダイレクトURI: http://127.0.0.1:8080/callback （デフォルトポート、環境変数で変更可能）
  • アプリケーションの Client ID と Client Secret を取得
  • 権限設定: 必要な機能の 参照・更新 にチェックを入れる

2. 環境変数の設定:

   FREEE_CLIENT_ID=your_client_id          # 必須: freeeアプリの Client ID
   FREEE_CLIENT_SECRET=your_client_secret  # 必須: freeeアプリの Client Secret
   FREEE_COMPANY_ID=your_company_id        # 必須: デフォルト事業所ID
   FREEE_CALLBACK_PORT=8080                # オプション: OAuthコールバックポート、デフォルトは 8080
   

   注意: FREEE_COMPANY_ID はデフォルト事業所として使用されます。実行時に freee_set_company ツールで他の事業所に切り替えることができます。

3. 認証方法:
   初回API使用時またはトークンの有効期限切れ時に、freee_authenticate ツールを使用して認証を行います。一度認証すると、同じトークンで複数の事業所にアクセスできます。

認証の仕組み

1. 永続コールバックサーバー: MCPサーバー起動時に指定ポート（デフォルト8080）でOAuthコールバック受付サーバーが起動します
2. 認証フロー: freee_authenticate ツール実行時にブラウザで認証ページが開き、認証後にコールバックを受信します
3. トークン保存: 認証後、トークンは ~/.config/freee-mcp/tokens.json にユーザーベースで安全に保存されます（ファイル権限600）
4. 自動更新: アクセストークンの有効期限が切れた場合、リフレッシュトークンを使用して自動的に更新されます
5. タイムアウト: 認証リクエストは5分でタイムアウトします

開発

# 開発サーバーの起動(ウォッチモード)
pnpm dev

# ビルド
pnpm build

# 型チェック
pnpm type-check

# リント
pnpm lint

# フォーマット
pnpm format

使用方法

ビルド後、以下のコマンドでサーバーを起動できます:

pnpm start

MCPサーバーとしての登録

Claude デスクトップアプリケーションで使用するには、以下の設定を ~/Library/Application Support/Claude/claude_desktop_config.json に追加してください:

{
  "mcpServers": {
    "freee": {
      "command": "/usr/local/bin/node",
      "args": [
        "/path/to/freee-mcp/dist/index.cjs"
      ],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id",
        "FREEE_CLIENT_SECRET": "your_client_secret",
        "FREEE_COMPANY_ID": "your_company_id",
        "FREEE_CALLBACK_PORT": "8080"
      }
    }
  }
}

VSCode拡張機能で使用する場合は、同様の設定を ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json に追加してください。

利用可能なツール

主要なMCPツール

• 認証管理: freee_authenticate, freee_auth_status, freee_clear_auth, freee_current_user
• 事業所管理: freee_set_company, freee_get_current_company, freee_list_companies
• ガイダンス: freee_help, freee_getting_started, freee_status

freee APIツール

freee APIのすべてのエンドポイントがMCPツールとして自動的に公開されます。各ツールは以下の命名規則に従います:

• GET: get_[resource_name]
• POST: post_[resource_name]
• PUT: put_[resource_name]_by_id
• DELETE: delete_[resource_name]_by_id

使い方

初回セットアップ

# 1. 使い方ガイドを確認
freee_help

# 2. 初回セットアップガイド
freee_getting_started

# 3. 現在の状態確認
freee_status

基本的なワークフロー

1. 事業所設定: freee_set_company [事業所ID]
2. 認証: freee_authenticate
3. API使用: get_deals, freee_current_user など

詳細な使用方法、事業所切り替え、トラブルシューティングについては、MCPツール内のガイダンス機能をご利用ください：

• freee_help - 全体的な使い方とワークフロー
• freee_getting_started - 初回セットアップの詳細ガイド
• freee_status - 現在の状態と推奨アクション

技術スタック

• TypeScript
• Model Context Protocol SDK
• OAuth 2.0 + PKCE認証
• Zod（バリデーション）
• esbuild（ビルド）
• Node.js HTTP server（OAuth コールバック）

ライセンス

ISC

関連リンク

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