BambooHR MCP

What is BambooHR MCP?

BambooHR MCP (Model Context Protocol) is a Node.js and TypeScript library that provides a type-safe interface for interacting with the BambooHR API. It simplifies access to employee data, time tracking, and HR management features.

How to use BambooHR MCP?

1. Installation:

   git clone https://github.com/encoreshao/bamboohr-mcp.git
   cd bamboohr-mcp
   npm install
   

2. Usage:

   Import the necessary functions and classes from bamboohr-mcp.

   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!;
   
   // Example: List all employees
   const directory = await fetchEmployeeDirectory(token, companyDomain);
   directory.employees.forEach((emp) => {
     console.log(`${emp.displayName} — ${emp.workEmail} — ${emp.jobTitle}`);
   });
   
   // Example: Fetch "who's out today"
   const whosOut = await fetchWhosOut(token, companyDomain);
   whosOut.forEach((out) => {
     console.log(`${out.employeeName}: ${out.startDate} to ${out.endDate}`);
   });
   

3. Environment Variables:

   Set the following environment variables or pass them directly to the methods:

   • BAMBOOHR_TOKEN: Your BambooHR API token.
   • BAMBOOHR_COMPANY_DOMAIN: Your BambooHR company domain (e.g., yourcompany if your URL is https://yourcompany.bamboohr.com).
   • BAMBOOHR_EMPLOYEE_ID: Your BambooHR employee ID.

   Example .env file:

   BAMBOOHR_TOKEN=your_api_token_here
   BAMBOOHR_COMPANY_DOMAIN=yourcompany
   BAMBOOHR_EMPLOYEE_ID=123
   

Key Features of BambooHR MCP

• TypeScript types: Provides type definitions for all BambooHR models and API responses, ensuring type safety.
• Promise-based API: Offers a simple, promise-based interface for all major BambooHR endpoints.
• Extensible: Designed to be easily extended and integrated into existing projects.
• Helper Functions: Includes convenient functions like fetchWhosOut, fetchProjects, submitWorkHours, getMe, fetchEmployeeDirectory, and fetchTimeEntries.

Use Cases of BambooHR MCP

• Employee Data Management: Retrieve and manage employee information such as names, emails, job titles, and directories.
• Time Tracking: Fetch "who's out" information and submit work hours.
• HR Automation: Automate various HR-related tasks by programmatically interacting with the BambooHR API.
• Custom Integrations: Build custom applications and integrations that leverage BambooHR data.

FAQ about BambooHR MCP

• How to create a BambooHR API Token?

  1. Log in to your BambooHR account.
  2. Click on your profile picture (bottom-left).
  3. Select "API Keys" from the dropdown.
  4. Click "Add New Key", enter a name, and click "Generate Key".
  5. Copy the token immediately (it's shown only once).

• How to find your BambooHR Company Domain? Your company domain is the subdomain in your BambooHR URL. For https://yourcompany.bamboohr.com, the domain is yourcompany.

• How to get your Employee ID? You can find your employee ID in your profile URL (e.g., https://yourcompany.bamboohr.com/employees/employee.php?id=123).

• How to extend BambooHR MCP? Add new methods in src/apis/bamboohr.ts and export them from src/index.ts.

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.