BambooHR MCP

What is BambooHR MCP about?

BambooHR MCP offers a TypeScript‑first, promise‑based library that abstracts BambooHR’s REST endpoints into strongly‑typed functions. It simplifies fetching employee data, time‑off information, projects, and submitting work hours, while ensuring compile‑time safety.

How to use BambooHR MCP?

1. Install

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

2. Set environment variables (or pass them directly to functions):

   BAMBOOHR_TOKEN=your_api_token
   BAMBOOHR_COMPANY_DOMAIN=yourcompany
   BAMBOOHR_EMPLOYEE_ID=123
   

3. Import and call helpers

   import { fetchEmployeeDirectory, fetchWhosOut, fetchProjects, submitWorkHours } from "bamboohr-mcp";
   
   const directory = await fetchEmployeeDirectory(process.env.BAMBOOHR_TOKEN!, process.env.BAMBOOHR_COMPANY_DOMAIN!);
   // work with the returned data
   

   The library also exposes a BambooHRApi class for custom extensions.

Key features of BambooHR MCP

• Full TypeScript typings for models and API responses.
• Promise‑based API that integrates naturally with async/await.
• Helper functions for common tasks: employee directory, who’s out, projects, time entries, work‑hour submission, and user profile.
• Modular design – add new endpoints by extending src/apis/bamboohr.ts and exporting from src/index.ts.
• Zero runtime dependencies beyond standard Node.js and node-fetch‑style HTTP client.

Use cases of BambooHR MCP

• Building internal dashboards that visualize employee availability and project allocations.
• Automating time‑sheet submissions from custom tooling.
• Syncing BambooHR employee data with other HR or payroll systems.
• Creating CLI utilities for HR administrators to query or update information quickly.
• Integrating BambooHR data into broader workflow‑automation platforms.

FAQ from the BambooHR MCP

Q: Do I need to run a server to use this library? A: No. It is a client‑side SDK that can be imported into any Node.js or TypeScript project.

Q: Which Node.js versions are supported? A: The repository uses modern ECMAScript syntax; Node.js 14+ is recommended.

Q: How are authentication credentials supplied? A: Pass the API token and company domain as function arguments or set the BAMBOOHR_TOKEN and BAMBOOHR_COMPANY_DOMAIN environment variables.

Q: Can I extend the library with my own API calls? A: Yes. Add new methods in src/apis/bamboohr.ts and export them via src/index.ts.

Q: Is there built‑in error handling? A: The helpers throw on HTTP errors; you can wrap calls in try/catch to handle them gracefully.

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.