BambooHR MCP

BambooHR MCP

一个面向 BambooHR 的模型上下文协议（MCP）库，使用 Node.js 和 TypeScript 构建。该库提供简洁且类型安全的接口，方便在 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 Key Name（例如“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 文件。