Access BambooHR Employee and Time Data

This is a Model Context Protocol library for BambooHR, built with Node.js and TypeScript, providing a type-safe interface to the BambooHR API. It exposes a BambooHRApi class plus standalone helper functions: fetchEmployeeDirectory (name, email, job title for all employees), fetchWhosOut (who is out and for what date range), fetchProjects (projects and their tasks for an employee), submitWorkHours (log hours against a specific project and task with a date, duration, and note), getMe (the authenticated employee's own profile), and fetchTimeEntries. All methods return Promises and use TypeScript types defined in src/utils/models.d.ts.

Use this when you want an AI assistant or Node.js/TypeScript application to look up employee directory information, check who's out today, browse projects and tasks, or submit work hours against a BambooHR project/task - all through a typed API instead of calling BambooHR's REST API directly.

Do NOT use this without a BambooHR API token, your company domain, and your employee ID configured - all three are required. Generate the token from your BambooHR profile's API Keys page; it is shown only once at creation.

• fetchEmployeeDirectory(token, companyDomain): list all employees with name, email, and job title.
• fetchWhosOut(token, companyDomain): list who is out and their start/end dates.
• fetchProjects(token, companyDomain, employeeID): list projects and their tasks for an employee.
• submitWorkHours(token, companyDomain, employeeID, projectId, taskId, date, hours, note): log work hours against a project/task.
• getMe: get the authenticated employee's own profile.
• fetchTimeEntries: retrieve logged time entries.

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}`);
});

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

Create a BambooHR API token from your BambooHR account: click your profile picture in the bottom-left corner, select "API Keys", click "Add New Key", name it (e.g. "MCP Server"), and click "Generate Key" - copy it immediately since it's only shown once. Your company domain is the subdomain in your BambooHR URL (e.g. yourcompany for https://yourcompany.bamboohr.com). Your employee ID can be read from your profile URL, e.g. https://yourcompany.bamboohr.com/employees/employee.php?id=123. Configure via a .env file:

BAMBOOHR_TOKEN=your_api_token_here
BAMBOOHR_COMPANY_DOMAIN=yourcompany
BAMBOOHR_EMPLOYEE_ID=123

Credentials can also be passed directly to each method instead of via environment variables. To extend the library, add new methods in src/apis/bamboohr.ts and export them from src/index.ts.

HR teams and developers building internal tools who want typed, promise-based access to BambooHR's employee directory, time-off, projects, and time-tracking data from Node.js/TypeScript or an AI assistant.