BambooHR MCP

BambooHR MCP

Node.js と TypeScript で構築された、BambooHR 用の Model Context Protocol（MCP）ライブラリです。このライブラリは、Node.js または TypeScript アプリケーションから BambooHR API を利用するための、シンプルで型安全なインターフェースを提供します。

特長

• すべてのモデルと API レスポンスに対応する TypeScript 型
• BambooHR の主要なすべてのエンドポイントに対応した、シンプルな Promise ベースの API
• 独自のプロジェクトへの拡張や統合が簡単

インストール

# Clone the repository
git clone https://github.com/encoreshao/bamboohr-mcp.git

# Navigate to the project directory
cd bamboohr-mcp

# Install dependencies
npm install

使用方法

import {
  BambooHRApi,
  fetchWhosOut,
  fetchProjects,
  submitWorkHours,
  getMe,
  fetchEmployeeDirectory,
  fetchTimeEntries,
} from "bamboohr-mcp";

const token = process.env.BAMBOOHR_TOKEN!;
const companyDomain = process.env.BAMBOOHR_COMPANY_DOMAIN!;
const employeeID = process.env.BAMBOOHR_EMPLOYEE_ID!;

// List all employees with name, email, and job title
const directory = await fetchEmployeeDirectory(token, companyDomain);
directory.employees.forEach((emp) => {
  console.log(`${emp.displayName} — ${emp.workEmail} — ${emp.jobTitle}`);
});

// Fetch "who's out today"
const whosOut = await fetchWhosOut(token, companyDomain);
whosOut.forEach((out) => {
  console.log(`${out.employeeName}: ${out.startDate} to ${out.endDate}`);
});

// Submit work hours (find project/task IDs first)
const projects = await fetchProjects(token, companyDomain, employeeID);
const bambooHR = projects.find((p) => p.name.includes("BambooHR"));
const devTask = bambooHR?.tasks.find((t) => t.name.includes("Development"));
if (bambooHR && devTask) {
  await submitWorkHours(
    token,
    companyDomain,
    employeeID,
    bambooHR.id,
    devTask.id,
    "2024-06-01",
    1,
    "Development work on BambooHR"
  );
}

API

すべてのメソッドは Promise を返し、src/utils/models.d.ts で定義された型を使用します。

• BambooHRApi クラス：すべての API メソッドをカプセル化します。
• ヘルパー関数：fetchWhosOut、fetchProjects、submitWorkHours、getMe、fetchEmployeeDirectory、fetchTimeEntries。

環境変数

BambooHR API トークンと会社のドメインは、メソッドに直接渡すか、環境変数を使用できます。

必須：

• BAMBOOHR_TOKEN — BambooHR API トークン
• BAMBOOHR_COMPANY_DOMAIN — BambooHR の会社ドメイン（.bamboohr.com より前の部分）
• BAMBOOHR_EMPLOYEE_ID — BambooHR の従業員 ID

BambooHR API トークンの作成

このライブラリを使用するには、BambooHR API トークンを作成する必要があります。

1. BambooHR アカウントにログインします
2. 左下のプロフィール画像をクリックします
3. ドロップダウンメニューから「API Keys」を選択します
4. 「Add New Key」をクリックします
5. キーの API キー名（例：「MCP Server」）を入力し、「Generate Key」をクリックします
6. 生成されたトークンをすぐにコピーします（トークンが表示されるのは一度だけです）

会社ドメインの確認

会社ドメインは、BambooHR の URL で使用されているサブドメインです。

• https://yourcompany.bamboohr.com で BambooHR にアクセスする場合、会社ドメインは yourcompany です
• この値は、環境変数 BAMBOOHR_COMPANY_DOMAIN に設定するか、API メソッドに直接渡します

従業員 ID の確認

従業員 ID は、次の方法で確認できます。

1. プロフィール URL から確認します：プロフィールを表示すると、URL に従業員 ID が含まれます（例：https://yourcompany.bamboohr.com/employees/employee.php?id=123）

.env ファイルの例：

BAMBOOHR_TOKEN=your_api_token_here
BAMBOOHR_COMPANY_DOMAIN=yourcompany
BAMBOOHR_EMPLOYEE_ID=123

拡張

src/apis/bamboohr.ts に新しいメソッドを追加し、src/index.ts からエクスポートします。

貢献者

• Encore Shao（github.com/encoreshao）

ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細は LICENSE ファイルを参照してください。