Skip to main content
Glama
0xkohe

freee-hr-mcp

by 0xkohe
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Freee HR MCP Server

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

概要

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

Related MCP server: leave-management

主な機能

  • 従業員管理: 従業員情報の取得、作成、更新、削除

  • 勤怠管理: 打刻、勤怠記録の取得・更新

  • 休暇管理: 有給休暇、特別休暇の管理

  • 申請承認: 各種申請の作成、承認

  • グループ管理: グループの作成、メンバー管理

  • 給与明細: 給与明細の取得

セットアップ

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

npm install

2. 環境変数の設定

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

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

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

  1. freee開発者サイトにアクセス

  2. アプリケーションを作成

  3. 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. 使用方法

  1. VSCodeでCopilot Chatパネルを開く（Cmd/Ctrl + Shift + I）

  2. チャットに @mcp と入力してMCPモードを有効化

  3. 初回接続時に認証情報の入力プロンプトが表示される

  4. 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日間の有給休暇を申請してください」

開発者向け情報

最新のfreee HR APIに更新する手順

freee APIが更新された場合、以下の手順で最新版に対応できます：

1. 一括更新（推奨）

# 最新のAPIスキーマ取得とコード生成を一括実行
npm run update-and-generate

# TypeScriptをビルド
npm run build

# 動作確認
npm start

2. 段階的な更新（デバッグ時）

# Step 1: 最新のOpenAPIスキーマを取得
npm run update-schema

# Step 2: コードを生成
npm run generate

# Step 3: ビルド
npm run build

# Step 4: 動作確認
npm start

OpenAPIスキーマの更新

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

npm run update-schema

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

コード生成

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

npm run generate

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

  1. Orvalによるコード生成

  2. post-generateスクリプトの実行

  3. datetime修正スクリプトの実行（.datetime()呼び出しの自動削除）

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

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

npm run update-and-generate

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

  1. 最新のOpenAPIスキーマをダウンロード

  2. Orvalでコードを生成

  3. 生成後の処理を実行

プロジェクト構造

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修正が適用されているか確認してください。

既知の問題と対処法

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

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

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

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

サポート

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

This server cannot be installed

F
license - not found
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/0xkohe/freee-hr-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server