BambooHR MCP

A Model Context Protocol (MCP) library for BambooHR, built with Node.js and TypeScript. This library provides a clean, type-safe interface to interact with the BambooHR API from your Node.js or TypeScript applications.

Features

• TypeScript types for all models and API responses
• Simple, promise-based API for all major BambooHR endpoints
• Easy to extend and integrate into your own projects

Installation

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

# Navigate to the project directory
cd bamboohr-mcp

# Install dependencies
npm install

Usage

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

All methods return Promises and use the types defined in `src/utils/models.d.ts`.

• `BambooHRApi` class: Encapsulates all API methods.
• Helper functions: `fetchWhosOut`, `fetchProjects`, `submitWorkHours`, `getMe`, `fetchEmployeeDirectory`, `fetchTimeEntries`.

Environment Variables

You can pass your BambooHR API token and company domain directly to the methods, or use environment variables:

Required:

• `BAMBOOHR_TOKEN` — Your BambooHR API token
• `BAMBOOHR_COMPANY_DOMAIN` — Your BambooHR company domain (the part before .bamboohr.com)
• `BAMBOOHR_EMPLOYEE_ID` — Your BambooHR employee ID

Creating a BambooHR API Token

To use this library, you'll need to create a BambooHR API token:

1. Log in to your BambooHR account

2. Click on your profile picture in the bottom-left corner

3. Select "API Keys" from the dropdown menu

4. Click "Add New Key"

5. Enter a API Key Name for your key (e.g., "MCP Server"), and click "Generate Key"

6. Copy the generated token immediately (it will only be shown once)

Finding Your Company Domain

Your company domain is the subdomain used in your BambooHR URL:

• If you access BambooHR at `https://yourcompany.bamboohr.com`, then your company domain is `yourcompany`
• This value should be used for the `BAMBOOHR_COMPANY_DOMAIN` environment variable or passed directly to the API methods

Getting Your Employee ID

You can find your employee ID in several ways:

1. From your profile URL: When viewing your profile, the URL will contain your employee ID (e.g., `https://yourcompany.bamboohr.com/employees/employee.php?id=123`)

Example .env file:

BAMBOOHR_TOKEN=your_api_token_here
BAMBOOHR_COMPANY_DOMAIN=yourcompany
BAMBOOHR_EMPLOYEE_ID=123

Extending

Add new methods in `src/apis/bamboohr.ts` and export them from `src/index.ts`.

Contributors

• Encore Shao (github.com/encoreshao)

License

This project is licensed under the MIT License. See the LICENSE file for details.