Freee HR MCP Server

freee人事労務APIをModel Context Protocol (MCP)経由で利用するためのサーバー実装です。

概要

このMCPサーバーは、freee人事労務のAPIをClaude Desktop等のMCP対応クライアントから利用できるようにします。OpenAPIスペックからOrvalを使用して自動生成されたコードをベースに構築されています。

主な機能

従業員管理: 従業員情報の取得、作成、更新、削除
勤怠管理: 打刻、勤怠記録の取得・更新
休暇管理: 有給休暇、特別休暇の管理
申請承認: 各種申請の作成、承認
グループ管理: グループの作成、メンバー管理
給与明細: 給与明細の取得

セットアップ

1. 依存関係のインストール

npm install

2. 環境変数の設定

以下の環境変数を設定してください：

export FREEE_HR_ACCESS_TOKEN="your_access_token_here"
export FREEE_HR_COMPANY_ID="your_company_id_here"

アクセストークンの取得方法

freee開発者サイトにアクセス
アプリケーションを作成
OAuth2.0認証フローでアクセストークンを取得

Company IDの取得方法

アクセストークン取得後、以下のコマンドで確認できます：

curl -X GET "https://api.freee.co.jp/hr/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

3. ビルド

npm run build

4. MCPサーバーの起動

npm start

Claude Desktopでの設定

claude_desktop_config.jsonに以下を追加：

{
  "mcpServers": {
    "freee-hr": {
      "command": "node",
      "args": ["/path/to/freee-hr-mcp/dist/server.js"],
      "env": {
        "FREEE_HR_ACCESS_TOKEN": "your_access_token_here",
        "FREEE_HR_COMPANY_ID": "your_company_id_here"
      }
    }
  }
}

VSCode + GitHub Copilotでの設定

1. 必要な拡張機能のインストール

VSCode拡張機能マーケットプレイスから以下をインストール：

GitHub Copilot
GitHub Copilot Chat

2. MCPサーバーの設定

プロジェクトのルートディレクトリに.vscode/settings.jsonを作成し、以下を追加：

{
  "github.copilot.chat.mcpServers": {
    "servers": {
      "freee-hr-mcp": {
        "type": "stdio",
        "command": "node",
        "args": ["dist/server.js"],
        "env": {
          "FREEE_HR_ACCESS_TOKEN": "${input:FREEE_HR_ACCESS_TOKEN}",
          "FREEE_HR_COMPANY_ID": "${input:FREEE_HR_COMPANY_ID}"
        }
      }
    },
    "inputs": [
      {
        "id": "FREEE_HR_ACCESS_TOKEN",
        "type": "promptString",
        "description": "freee access token"
      },
      {
        "id": "FREEE_HR_COMPANY_ID",
        "type": "promptString",
        "description": "freee company_id"
      }
    ]
  }
}

この設定により、MCPサーバー起動時に認証情報の入力を求められるため、セキュアに利用できます。

3. 使用方法

VSCodeでCopilot Chatパネルを開く（Cmd/Ctrl + Shift + I）
チャットに @mcp と入力してMCPモードを有効化
初回接続時に認証情報の入力プロンプトが表示される
freee人事労務の操作を依頼

VSCode Copilotでの使用例

// Copilot Chatでの使用例
@mcp freeeで従業員一覧を取得してください

@mcp 今月の勤怠データを確認して、残業時間が多い従業員をリストアップして

@mcp 有給休暇の残日数を全従業員分取得してCSV形式で出力して

環境変数を使用した設定（オプション）

環境変数から認証情報を読み込む場合は、以下の設定を使用：

{
  "github.copilot.chat.mcpServers": {
    "servers": {
      "freee-hr-mcp": {
        "type": "stdio",
        "command": "node",
        "args": ["dist/server.js"],
        "env": {
          "FREEE_HR_ACCESS_TOKEN": "${env:FREEE_HR_ACCESS_TOKEN}",
          "FREEE_HR_COMPANY_ID": "${env:FREEE_HR_COMPANY_ID}"
        }
      }
    }
  }
}

この場合、事前に環境変数を設定しておく必要があります：

export FREEE_HR_ACCESS_TOKEN="your_access_token"
export FREEE_HR_COMPANY_ID="your_company_id"

使用例

Claude Desktopで以下のような操作が可能です：

従業員一覧の取得

「従業員の一覧を取得してください」

勤怠打刻

「出勤打刻をしてください」

勤怠記録の確認

「今月の勤怠記録を表示してください」

有給休暇の申請

「明日から2日間の有給休暇を申請してください」

開発者向け情報

OpenAPIスキーマの更新

freeeの最新APIスキーマを取得：

npm run update-schema

このコマンドは、freeeの公式GitHubリポジトリから最新のOpenAPIスキーマをダウンロードします。

コード生成

OpenAPIスペックから最新のコードを生成：

npm run generate

このコマンドは以下を実行します：

Orvalによるコード生成
post-generateスクリプトの実行
datetime修正スクリプトの実行（.datetime()呼び出しの自動削除）

スキーマ更新とコード生成を一括実行

最新のAPIスキーマを取得してコードを再生成：

npm run update-and-generate

このコマンドは以下を順番に実行します：

最新のOpenAPIスキーマをダウンロード
Orvalでコードを生成
生成後の処理を実行

プロジェクト構造

freee-mcp2/
├── src/
│   ├── server.ts          # MCPサーバーのエントリーポイント
│   ├── handlers.ts        # 自動生成されたハンドラー
│   ├── http-client.ts     # 自動生成されたHTTPクライアント
│   ├── tool-schemas.zod.ts # 自動生成されたZodスキーマ
│   ├── custom-fetch.ts    # カスタムfetch実装（認証等）
│   └── http-schemas/      # 自動生成された型定義
├── openapi/
│   └── freee-hr.json      # freee人事労務のOpenAPIスペック
├── scripts/
│   ├── post-generate.js   # 生成後の処理スクリプト
│   └── update-openapi-schema.sh # OpenAPIスキーマ更新スクリプト
├── fix-datetime.js        # datetime修正スクリプト
└── orval.config.mjs       # Orval設定ファイル

トラブルシューティング

環境変数エラー

Error: FREEE_HR_ACCESS_TOKEN environment variable is required

→ 環境変数が正しく設定されているか確認してください。

認証エラー（401）

Status: 401 Unauthorized

→ アクセストークンの有効期限を確認してください。

datetime関連のエラー

Invalid datetime string

→ npm run generateを実行して、datetime修正が適用されているか確認してください。

既知の問題と対処法

POST/PUTリクエストのボディが送信されない

custom-fetch.tsでbodyフィールドをdataフィールドに変換して対応

datetime()によるタイムゾーン付き日時の検証エラー

fix-datetime.jsで自動的に.datetime()を削除して対応

サポート

問題が発生した場合は、Issueを作成してください。

freee-hr-mcp