Freee Hr MCP

Freee HR MCP服务器

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"

如何获取访问令牌

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 聊天助手

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转换为字段

1. datetime()验证带时区的日期和时间时出错

- fix-datetime.js自动.datetime()删除并支持

支持

在您查看完详细信息后，单击Issue中所述修改相应参数的值。